Publish Claude Code Binaries / Stage and publish binaries (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-arm64 (push) Canceled after 0s
Publish Tutti App Runtime / Build darwin-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build linux-amd64 (push) Canceled after 0s
Publish Tutti App Runtime / Build windows-amd64 (push) Canceled after 0s
Sync Tutti Agent Skills / sync (push) Canceled after 0s
Windows Agent Adapters / Test Windows agent adapters (push) Canceled after 0s
Windows Daemon Adapters / Test Windows daemon adapters (push) Canceled after 0s
Publish Tutti App Runtime / Publish runtime catalog (push) Canceled after 0s
1048 lines
60 KiB
Markdown
1048 lines
60 KiB
Markdown
# Troubleshooting: Toolchain, Browser, And Terminal
|
||
|
||
[Back to troubleshooting index](./README.md)
|
||
|
||
### Standalone Agent provider login reports an internal error
|
||
|
||
- Symptom:
|
||
A provider login request fails in a standalone Agent window even though a
|
||
Workbench host appears to be bound, or an HTTP/file action unexpectedly opens
|
||
an OS application.
|
||
- Quick checks:
|
||
Distinguish the AgentGUI `surface.host` from the standalone right-side tool
|
||
host. Verify that the renderer registered the workspace-scoped Terminal,
|
||
Browser, and Files presenters before announcing tool-host readiness.
|
||
- Root cause:
|
||
The AgentGUI surface host owns the Agent node, not Desktop tool nodes. Reusing
|
||
it as a Workspace Workbench host makes Terminal launch return no node, while
|
||
standalone-specific link/file shortcuts can bypass the in-app tools.
|
||
- Fix:
|
||
Keep semantic launch coordinators shared and register Desktop presentation
|
||
adapters per mode. The standalone adapter creates/selects sidebar tabs and
|
||
reserves OS navigation for explicit external or reveal actions.
|
||
- Validation:
|
||
Verify provider login opens a new Terminal tab, ordinary HTTP and file
|
||
preview stay in right-side tools, explicit Open in Finder remains external,
|
||
and Browser automation follows the canonical Turn's validated renderer claim
|
||
(with Workspace fallback only for an unclaimed legacy Turn).
|
||
|
||
### Go-only PR skips a repository contract that later fails
|
||
|
||
- Symptom:
|
||
A Go-only PR is green, but a later TypeScript PR fails an unrelated
|
||
repository-wide check or tool test against the Go change.
|
||
- Quick checks:
|
||
Inspect whether the failing command scans repository-wide files, generated
|
||
artifacts, workflows, hooks, or architecture boundaries. Then check whether
|
||
CI attached it to `run_ts` only because the checker is implemented in
|
||
JavaScript or TypeScript.
|
||
- Root cause:
|
||
Check ownership was classified by implementation language instead of checked
|
||
responsibility. Generated-source paths and non-code package assets could also
|
||
be absent from inline workflow path predicates.
|
||
- Fix:
|
||
Register repository policy, tool contract, generated contract, or boundary
|
||
checks in `repository-checks.mjs`. Keep TypeScript and Go jobs limited to
|
||
language-owned lint and tests. Reuse `change-classification.mjs` in local and
|
||
PR validation.
|
||
- Validation:
|
||
Add selector fixtures for every source-of-truth path and a narrow workflow
|
||
contract test that verifies repository groups stay outside language jobs.
|
||
Confirm a Go-only fixture does not select TypeScript validation.
|
||
- References:
|
||
[repository-checks.mjs](../../../tools/scripts/repository-checks.mjs)
|
||
[change-classification.mjs](../../../tools/scripts/change-classification.mjs)
|
||
[testing.md](../testing.md)
|
||
|
||
### Goal recovery Go tests fail only in the full workspace lane
|
||
|
||
- Symptom:
|
||
`services/tuttid/service/agent` goal recovery tests pass alone but fail in the
|
||
pull-request Go workspace job with `recover goal operation ...: context
|
||
deadline exceeded`. The failing test can take several seconds even though its
|
||
fake provider timeout is configured for 20–25 milliseconds.
|
||
- Quick checks:
|
||
Inspect whether the test uses a small real
|
||
`GoalOperationAttemptTimeout` around the entire worker step. Compare the CI
|
||
duration with the configured timeout and check whether the fake provider hook
|
||
was reached before changing Host retry or lease semantics.
|
||
- Root cause:
|
||
The attempt context also covers actor acquisition and SQLite work before the
|
||
fake provider call. Under concurrent Go workspace load, the runner may not
|
||
schedule that work within a 20–25 millisecond test window. The context then
|
||
expires before the intended fake deadline path, so the worker reports an
|
||
infrastructure timeout instead of exercising retry persistence.
|
||
- Fix:
|
||
For deadline classification and retry-budget tests, return
|
||
`context.DeadlineExceeded` directly from the fake provider. Use a
|
||
test-controlled deadline context when cancellation propagation and detached
|
||
lease persistence are the behavior under test. Reserve real wall-clock
|
||
deadlines for end-to-end budget tests and give those assertions enough
|
||
scheduling margin for the full workspace lane. Do not add retries or change
|
||
production lifecycle timeouts to mask the test race.
|
||
- Validation:
|
||
Run the affected goal tests repeatedly with shuffled order, then run the full
|
||
agent-service package and changed-aware validation.
|
||
- References:
|
||
[service_test.go](../../../services/tuttid/service/agent/service_test.go)
|
||
[Testing](../testing.md)
|
||
|
||
### gomobile Android AAR fails after Go compilation succeeds
|
||
|
||
- Symptom:
|
||
`GOOS=android GOARCH=arm64 CGO_ENABLED=0 go build ./...` succeeds, but
|
||
`gomobile bind` either reports `gobind was not found` after `gomobile init`,
|
||
or fails while linking `libgojni.so` with
|
||
`github.com/wlynxg/anet: invalid reference to net.zoneCache`.
|
||
- Quick checks:
|
||
Confirm the module pins `golang.org/x/mobile` at a version compatible with the
|
||
repository Go baseline. Run `go mod why -m github.com/wlynxg/anet`; Pion ICE
|
||
reaches it through the Android network enumeration path. Check whether
|
||
`gobind` is actually present on `PATH` during the bind subprocess rather than
|
||
assuming `gomobile init` installed it globally.
|
||
- Root cause:
|
||
`go tool gomobile` runs the pinned tool without installing its sibling
|
||
`gobind` executable. Separately, `anet` uses `go:linkname` for the Go network
|
||
zone cache, and Go 1.23 or newer rejects that internal reference unless the
|
||
linker compatibility flag is explicit. A no-CGO package compile does not
|
||
exercise the same shared-library link step as an AAR build.
|
||
- Fix:
|
||
Build the module-selected `golang.org/x/mobile/cmd/gobind` into an isolated
|
||
temporary `GOBIN`, prepend that directory to `PATH` only for `gomobile bind`,
|
||
and pass `-ldflags=-checklinkname=0` only to that gomobile build. Pin the NDK
|
||
version through `ANDROID_NDK_HOME`; do not add a local `anet` fork or disable
|
||
linker checks for ordinary host builds.
|
||
- Validation:
|
||
Run `make android-crosscompile`, `make android-bindings-check`, and
|
||
`make android-aar`. The final check must validate the Java binding and
|
||
`armeabi-v7a`, `arm64-v8a`, `x86`, and `x86_64` `libgojni.so` entries. A real
|
||
Android device or emulator is still required to execute the loopback probe.
|
||
- References:
|
||
[DeviceLink Makefile](../../../packages/device-link/Makefile)
|
||
[DeviceLink README](../../../packages/device-link/README.md)
|
||
|
||
### Android ICE probe gathers no candidates
|
||
|
||
- Symptom:
|
||
A gomobile DeviceLink probe loads its JNI library and enters Go successfully,
|
||
but `LocalParams` reports that the ICE agent gathered no candidates even
|
||
when loopback candidates are enabled.
|
||
- Quick checks:
|
||
Confirm the test or host app declares
|
||
`android.permission.INTERNET` in its manifest before changing ICE filters or
|
||
Android interface-enumeration code.
|
||
- Root cause:
|
||
Android applies the `INTERNET` manifest permission to network sockets. A
|
||
minimal hand-built probe APK can omit it even though normal application
|
||
templates usually include it, leaving Pion unable to bind a UDP candidate.
|
||
- Fix:
|
||
Add the `INTERNET` permission to the probe or product manifest. Do not add an
|
||
Android-only candidate fallback to the shared transport core for this case.
|
||
- Validation:
|
||
Run the signed probe on an Android device or emulator and require a
|
||
`TuttiDeviceLinkProbe` log entry containing `PASS epoch=1` and the expected
|
||
echoed payload.
|
||
- References:
|
||
[Probe manifest](../../../packages/device-link/mobile/androidprobe/AndroidManifest.xml)
|
||
[DeviceLink README](../../../packages/device-link/README.md)
|
||
|
||
### Temporary Git fixture turns a linked worktree bare
|
||
|
||
- Symptom:
|
||
A test run leaves the shared repository config with `core.bare=true`, writes
|
||
fixture author identity into `.git/config`, or creates an `init` commit that
|
||
deletes most tracked files from a linked-worktree branch.
|
||
- Quick checks:
|
||
Run `git config --show-origin --get core.bare`, inspect local `user.name` and
|
||
`user.email`, then inspect the affected branch reflog for a fixture-authored
|
||
commit. Search the responsible test for temporary-repository Git commands
|
||
whose child environment inherits `GIT_DIR` or `GIT_WORK_TREE`.
|
||
- Root cause:
|
||
`mkdtemp` isolates files, not Git repository selection. An inherited
|
||
linked-worktree `GIT_DIR` overrides the fixture cwd, so `git init` reinitializes
|
||
the caller's private worktree metadata and updates its shared common config.
|
||
Later fixture `add` and `commit` commands can then stage the fixture tree
|
||
against the real branch.
|
||
- Fix:
|
||
Remove repository-local Git environment variables at the validation-lane
|
||
spawn boundary and for every fixture Git command using case-insensitive name
|
||
matching. Let normal lanes rediscover the repository from their cwd. For
|
||
fixtures, also set `GIT_CEILING_DIRECTORIES` to the fixture root, stop on any
|
||
command failure, verify `--absolute-git-dir` after initialization, and pass
|
||
fixture author identity through commit-local `-c` arguments instead of
|
||
`git config`.
|
||
- Validation:
|
||
Run `run-validation-lanes.test.mjs` to confirm spawned lanes remove poisoned
|
||
Git selectors while preserving unrelated environment, then run
|
||
`git-environment.test.mjs`, which launches the temporary-repository test suites
|
||
with a poisoned linked-worktree `GIT_DIR` that points only at a disposable
|
||
repository. Confirm each fixture initializes its own `.git`, then verify the
|
||
caller's config and branch remain unchanged. Keep the lower-level environment
|
||
test coverage for `GIT_WORK_TREE` and `GIT_CONFIG_*` inputs.
|
||
- References:
|
||
[git-environment.mjs](../../../tools/scripts/git-environment.mjs)
|
||
[run-validation-lanes.mjs](../../../tools/scripts/run-validation-lanes.mjs)
|
||
[check-agent-gui-degradation.test.mjs](../../../tools/scripts/check-agent-gui-degradation.test.mjs)
|
||
[push-checked.test.mjs](../../../tools/scripts/push-checked.test.mjs)
|
||
[run-check-changed.test.mjs](../../../tools/scripts/run-check-changed.test.mjs)
|
||
[static-analysis.md](../static-analysis.md)
|
||
|
||
### Dynamic CLI input rejects plausible flags
|
||
|
||
- Symptom:
|
||
A dynamic `tutti-dev` command prints normal-looking help, but invocation fails
|
||
with `invalid input "<flag>"` or an app-level invalid-argument error even
|
||
though the flag name and shell syntax are correct.
|
||
- Quick checks:
|
||
Inspect the command input struct tags under `services/tuttid/service/cli/providers`.
|
||
Confirm `validate:"min=...,max=..."` bounds and any finite string values such
|
||
as status, priority, or source are represented in the framework input schema.
|
||
- Root cause:
|
||
Dynamic CLI help and agent command guides are generated from daemon capability
|
||
schema, while actual invocation is bound and validated later by the daemon.
|
||
If the schema omits enum/range metadata, agents may guess plausible but
|
||
invalid values such as `--status open` or an out-of-range page size.
|
||
- Fix:
|
||
Keep finite string sets in `enum:"..."` tags and numeric bounds in
|
||
`validate:"min=...,max=..."`. The framework should reject invalid enum/range
|
||
input with a reason before provider code sees the request.
|
||
- Validation:
|
||
Add provider tests that assert both advertised schema metadata and invalid
|
||
input errors for the affected command.
|
||
- References:
|
||
[input.go](../../../services/tuttid/service/cli/framework/input.go)
|
||
[issues.go](../../../services/tuttid/service/cli/providers/issuemanager/issues.go)
|
||
|
||
### GitHub Actions pnpm setup fails with ERR_PNPM_BAD_PM_VERSION
|
||
|
||
- Symptom:
|
||
GitHub Actions jobs fail in the `pnpm/action-setup` step with
|
||
`ERR_PNPM_BAD_PM_VERSION` or "Multiple versions of pnpm specified" after
|
||
`package.json` gains an integrity-pinned `packageManager` value such as
|
||
`pnpm@10.11.0+sha512...`.
|
||
- Quick checks:
|
||
Inspect every workflow that uses `pnpm/action-setup`. If the workflow passes
|
||
`with.version` while the root `package.json` also declares `packageManager`,
|
||
the action sees two pnpm targets.
|
||
- Root cause:
|
||
`pnpm/action-setup` reads `packageManager` from `package.json` by default.
|
||
Passing a separate `version` input duplicates the same version source, and an
|
||
integrity-pinned `packageManager` string makes the mismatch explicit.
|
||
- Fix:
|
||
Keep `package.json` as the single pnpm version source. Remove the
|
||
`with.version` input from `pnpm/action-setup` steps instead of weakening the
|
||
root `packageManager` integrity pin.
|
||
- Validation:
|
||
Search workflows for `pnpm/action-setup` and confirm no step still passes a
|
||
`version` input. Push a new commit to rerun the PR checks.
|
||
|
||
### Multi-entry declaration build exhausts its worker heap or dominates release time
|
||
|
||
- Symptom:
|
||
A package build finishes its ESM phase, then fails during `DTS Build start`
|
||
with `ERR_WORKER_OUT_OF_MEMORY`. The failure is more frequent when
|
||
`check:changed --push-ready` runs package builds beside tests and other
|
||
builds, while an isolated retry may pass.
|
||
- Quick checks:
|
||
Confirm the error comes from tsup's declaration worker after the JavaScript
|
||
output reports success. Measure an isolated build with `/usr/bin/time -l`
|
||
and compare the package's declaration entry count; raising the parent Node
|
||
heap does not prove the worker's declaration graph is bounded.
|
||
- Root cause:
|
||
tsup asks its declaration worker to typecheck and roll up every configured
|
||
entry together. A package with many overlapping public entrypoints can keep
|
||
repeated TypeScript and Rollup declaration graphs until it approaches the V8
|
||
heap limit. Splitting entries across workers bounds each heap, but every
|
||
worker still repeats much of the same TypeScript analysis and can make the
|
||
declaration phase dominate release time.
|
||
- Fix:
|
||
Keep the runtime bundle as one build. Pre-emit unbundled declarations once
|
||
with the repository-pinned native TypeScript compiler and a declaration-only
|
||
tsconfig whose root files exactly match the runtime entries. Then let a
|
||
bounded set of tsup workers roll up the emitted declarations and remove the
|
||
intermediate tree. Keep workspace source path mappings out of the
|
||
declaration-only config so dependency sources do not leak into the package
|
||
emit. Test that the runtime entries, declaration roots, rollup groups, and
|
||
published type paths stay aligned. Do not make a global `NODE_OPTIONS`
|
||
increase the default fix; it preserves the oversized declaration graph and
|
||
moves the failure threshold.
|
||
- Validation:
|
||
Measure the isolated package build before and after, run the entry-coverage
|
||
test, typecheck imports from both the root and a subpath declaration, run the
|
||
package pack check, and reproduce the original changed-aware concurrent
|
||
build without a heap override.
|
||
- References:
|
||
[agentGuiBuildEntries.ts](../../../packages/agent/gui/build/agentGuiBuildEntries.ts)
|
||
[tsup.dts.config.ts](../../../packages/agent/gui/tsup.dts.config.ts)
|
||
[tsup.dts.config.test.ts](../../../packages/agent/gui/tsup.dts.config.test.ts)
|
||
|
||
### Browser CLI cold start timeout looks like an unreachable daemon
|
||
|
||
- Symptom:
|
||
An agent runs a command such as `tutti-dev browser list-pages` and gets
|
||
`daemon is not reachable`, but desktop and daemon logs show `tuttid` is
|
||
running and a Chrome or browser-use process may still appear.
|
||
- Quick checks:
|
||
Confirm the listener file under the active `TUTTI_STATE_DIR` has a live
|
||
address and token, then run `tutti-dev status --json`. If status succeeds
|
||
but the browser command fails after roughly the CLI client timeout, inspect
|
||
whether the first browser command is lazily starting `chrome-devtools-mcp` or
|
||
another browser backend. For browser backend overrides, inspect
|
||
`TUTTI_BROWSER_MCP_COMMAND`, `TUTTI_BROWSER_MCP_ARGS`, and the packaged
|
||
desktop's internal `TUTTI_BROWSER_MCP_ENTRY_PATH` handoff. Packaged desktop
|
||
handoffs should launch that vendored entry with the daemon's managed
|
||
`node-static` runtime, not a bare `node` from the user's `PATH`.
|
||
- Root cause:
|
||
Browser commands can do a cold start on first use. The daemon may launch the
|
||
browser backend while the CLI HTTP request is still waiting for the daemon to
|
||
finish the tool call. If the CLI client times out first and collapses every
|
||
transport error into `daemon is not reachable`, the message describes the
|
||
timeout incorrectly instead of the daemon's actual reachability.
|
||
- Fix:
|
||
Keep the CLI daemon client timeout long enough for browser backend cold
|
||
starts, and report request timeouts separately from connection failures.
|
||
Avoid treating a visible browser window as proof that the browser tool call
|
||
has completed.
|
||
- Validation:
|
||
Add CLI client tests for the default timeout and timeout-specific error
|
||
message. For a live smoke test, verify `tutti-dev status --json` succeeds and
|
||
then run the browser command again after the first cold start settles.
|
||
- References:
|
||
[client.go](../../../apps/cli/internal/daemon/client.go)
|
||
[session.go](../../../services/tuttid/service/browser/session.go)
|
||
[command.go](../../../services/tuttid/service/browser/command.go)
|
||
|
||
### Browser Agent retries plausible commands that the CLI rejects
|
||
|
||
- Symptom:
|
||
An Agent eventually opens the requested page but its transcript contains
|
||
repeated failures such as `browser open` returning `command_not_found`,
|
||
`json output is not supported`, or a cold `navigate` returning
|
||
`target closed while handling command`.
|
||
- Quick checks:
|
||
Inspect the session's exact tool calls rather than relying on the final Agent
|
||
message. Compare the Browser command-group help with each leaf command's
|
||
advertised output modes, and check whether the first operation tried to
|
||
navigate a selected page before any workspace Browser page existed.
|
||
- Root cause:
|
||
`open` was an intuitive but missing command, command-group help advertised a
|
||
generic `--json` flag even when leaf commands rejected JSON, and the Browser
|
||
skill led with page-scoped `navigate` instead of page-creating `new_page`.
|
||
Providers therefore converged on different retry sequences and surfaced
|
||
avoidable failures before finding a working command.
|
||
- Fix:
|
||
Provide `browser open --url <url>` as the direct page-creation path, keep
|
||
`new-page` for explicit tab management, support JSON consistently across the
|
||
Browser command family, and advertise `--json` only on leaf commands that
|
||
support it. Lead the Browser skill with `open`; reserve `navigate` for an
|
||
already selected page.
|
||
- Validation:
|
||
Test that `browser.open` maps to `new_page` with the exact workspace and Agent
|
||
session, that every Browser command accepts JSON output, and that CLI help
|
||
does not promise JSON for unsupported commands. In a live Agent session,
|
||
send `/browser` with a public URL and confirm the first Browser command
|
||
succeeds without retries.
|
||
- References:
|
||
[commands.go](../../../services/tuttid/service/cli/providers/browser/commands.go)
|
||
[run.go](../../../apps/cli/internal/app/run.go)
|
||
[browser-use skill template](../../../packages/agent/runtimeprep/skill_templates/browser-use.md)
|
||
|
||
### Malformed user skill frontmatter breaks skill discovery
|
||
|
||
- Symptom:
|
||
Agent logs include `failed to load skill ... missing YAML frontmatter
|
||
delimited by ---`, and the composer skill picker may show partial or
|
||
confusing skill results.
|
||
- Quick checks:
|
||
Search daemon logs for `skill_frontmatter_invalid`, then inspect the logged
|
||
`skillPath`. User-owned `~/.codex/skills/*/SKILL.md` and
|
||
`~/.agents/skills/*/SKILL.md` files must start with a `---` line and include
|
||
a closing `---` line before the body.
|
||
- Root cause:
|
||
Provider-native skill loaders expect delimited YAML frontmatter. If Tuttid
|
||
exposes a malformed user skill into provider runtime state, or includes it in
|
||
composer skill options, one bad local skill can pollute diagnostics around
|
||
otherwise valid skills.
|
||
- Fix:
|
||
Skip user Codex skill folders with malformed frontmatter before exposing them
|
||
under the session `CODEX_HOME/skills`, and skip malformed provider skills
|
||
during composer skill option discovery so valid sibling skills continue to be
|
||
recognized. Emit a structured warning with
|
||
`error_code=skill_frontmatter_invalid` whenever a malformed skill is skipped.
|
||
- Validation:
|
||
Add tests with malformed personal `.codex` and `.agents` skills beside valid
|
||
skills, then run `pnpm lint:go` and
|
||
`cd services/tuttid && go test ./... && go build ./...`.
|
||
- References:
|
||
[codex.go](../../../packages/agent/runtimeprep/codex.go)
|
||
[skill_options.go](../../../services/tuttid/service/agent/skill_options.go)
|
||
|
||
### Browser Node failed navigation renders a blank panel
|
||
|
||
- Symptom:
|
||
Opening an unreachable URL or an HTTP error page in Browser Node shows an
|
||
empty panel or `about:blank`/Chromium error state instead of the package error
|
||
card.
|
||
- Quick checks:
|
||
Inspect desktop logs for `Browser Node guest navigation failed` or
|
||
`Browser Node guest navigation returned HTTP error`, then confirm the
|
||
renderer runtime keeps `error` after later `state` events. In DevTools, do
|
||
not stop at the `<webview src="about:blank">`; verify whether the React error
|
||
card is present in the DOM and whether a later state event removed it.
|
||
- Root cause:
|
||
Electron emits several events for the same failed navigation. If
|
||
`did-fail-load` or an HTTP status error emits an error before a later
|
||
`publishState`, a runtime reducer that clears errors from ordinary state
|
||
updates can erase the error card and leave only the blank webview. Browser
|
||
event subscriptions tied only to mounted node components can also miss events
|
||
while the workbench node body is not mounted.
|
||
- Fix:
|
||
Treat `did-fail-load` and HTTP `did-navigate` status codes as Browser Node
|
||
navigation failures, publish any immediate state first, and emit the final
|
||
error after it. Keep runtime errors through non-loading state updates and
|
||
ignore Chromium internal error URLs such as `chrome-error://chromewebdata/`
|
||
when preserving the user-facing URL. Keep a workspace-level browser service
|
||
connected to the Browser Node feature so host events are not owned only by
|
||
React component mount effects.
|
||
- Validation:
|
||
Add package tests that HTTP `>=400` emits `navigation-failed`, that failed
|
||
navigations leave the error as the final event, that `did-fail-load` and
|
||
`loadURL` rejection are not double-counted, and that runtime errors survive
|
||
Chromium error-page state. For desktop integration, add coverage that browser
|
||
events update runtime state without mounting the Browser Node component.
|
||
- References:
|
||
[guestManager.ts](../../../packages/browser/workbench-node/src/electron-main/guestManager.ts)
|
||
[runtimeStore.ts](../../../packages/browser/workbench-node/src/core/runtimeStore.ts)
|
||
[workspaceBrowserService.ts](../../../apps/desktop/src/renderer/src/features/workspace-workbench/services/internal/workspaceBrowserService.ts)
|
||
[BrowserNode.tsx](../../../packages/browser/workbench-node/src/react/BrowserNode.tsx)
|
||
|
||
### Browser Node same-origin target-blank link does nothing
|
||
|
||
- Symptom:
|
||
Clicking a `target="_blank"` link in the full workspace Browser leaves the
|
||
current page unchanged and opens no tab. Desktop logs show the guest preload
|
||
reporting `action=open-url` with `defaultPrevented=true`, followed by both
|
||
`Browser Node guest open-url IPC received` and the guest `open-url` emission,
|
||
but no navigation to the requested URL. Cross-origin popup links may still
|
||
appear to work. A partial host fix can instead create a new tab whose first
|
||
guest URL is the product home page, such as Google, for every requested link.
|
||
- Quick checks:
|
||
Compare the current and requested origins. Confirm the event's
|
||
`sourceNodeId` names an existing `:tab:*` child and that the workspace Browser
|
||
route is registered with source `browser`.
|
||
- Root cause:
|
||
The guest preload correctly suppresses Chromium's native popup and delegates
|
||
the URL to the host. Reusing the Browser surface through Workbench activation
|
||
then changed only the active tab's `defaultUrl`. Browser Node's passive host
|
||
synchronization intentionally ignores same-origin differences to avoid
|
||
fighting in-page and authentication redirects, so the explicit popup URL was
|
||
never loaded. After routing the popup into a real tab, there is a second
|
||
materialization boundary: the active child has no runtime state until its
|
||
guest mounts. Falling straight back to the static product home page at that
|
||
point synchronizes the home page over the new tab's requested URL.
|
||
- Fix:
|
||
Keep the same-origin synchronization guard. Route Browser-owned `open-url`
|
||
events by their exact source child ID, create and select a new tab on that
|
||
Browser surface, and retain the existing Workbench launch fallback for URLs
|
||
emitted by Workspace Apps or unavailable Browser surfaces. Treat the route
|
||
registration as a Workbench-session resource: replace an earlier route for
|
||
the same workspace/source generation and dispose all workspace routes when
|
||
its session closes. In the package Workbench adapter, resolve the active tab's
|
||
stored URL before the static product home while runtime state is absent;
|
||
explicit activation and restored runtime state must keep higher priority.
|
||
- Validation:
|
||
Cover a same-origin popup from an existing Browser child and assert that a
|
||
second selected tab owns the requested URL while no Workbench launch occurs.
|
||
Also resolve the new tab before it has runtime state and assert its requested
|
||
URL wins over the product home page.
|
||
Rebuild the Browser contribution and assert only the latest feature receives
|
||
the popup, then dispose the workspace and assert its feature no longer
|
||
receives events. Also retain coverage that Workspace App URLs still launch
|
||
through the workspace Browser coordinator.
|
||
- References:
|
||
[workspaceBrowserService.ts](../../../apps/desktop/src/renderer/src/features/workspace-workbench/services/internal/workspaceBrowserService.ts)
|
||
[tabsStore.ts](../../../packages/browser/workbench-node/src/core/tabsStore.ts)
|
||
[nodeController.ts](../../../packages/browser/workbench-node/src/core/nodeController.ts)
|
||
|
||
### Workspace App authorization opens two Browser windows
|
||
|
||
- Symptom:
|
||
One Workspace App connection action opens two internal Browser windows for
|
||
the same authorization URL.
|
||
- Quick checks:
|
||
Starting from one user action, count Electron window-open producer callbacks,
|
||
`workspace app emitted open-url` events, Workbench launch requests, and
|
||
materialized Browser surfaces. Popup events should report
|
||
`producer=window-open-handler`. Equal URLs do not prove duplicate delivery,
|
||
and different OAuth query parameters do not prove separate user intent.
|
||
- Root cause:
|
||
Intercepting one cross-origin blank-link in preload while also installing
|
||
Electron's window-open handler creates two popup transports. A downstream
|
||
workspace, source node, local UUID, or URL cannot prove that independently
|
||
produced events represent one user action. Renderer deduplication therefore
|
||
masks the producer boundary and can merge intentional popup requests.
|
||
- Fix:
|
||
Leave blank links, `window.open`, and popup forms to Electron's
|
||
`setWindowOpenHandler`; preload must not globally intercept clicks or patch
|
||
page APIs. Install one delegate while attaching the guest and give its
|
||
host-provided Workspace App route priority. Browser Node `registerGuest` may
|
||
update only the delegate's ordinary Browser route; it must not install a
|
||
second handler. Main compares accepted HTTP(S) targets with the current guest
|
||
origin: internal URLs navigate the current guest after the handler returns
|
||
`deny`, while external URLs emit one Browser event. Reject POST and
|
||
empty/`about:blank` deferred popups with localized feedback instead of losing
|
||
the request body or later navigation. Keep the renderer as a stateless
|
||
one-event/one-launch adapter.
|
||
- Validation:
|
||
Start from one real internal popup and assert one producer callback, current
|
||
guest navigation, and zero Browser events, launches, surfaces, and native
|
||
child windows. Then start from one real external popup and assert producer
|
||
callback count one, Browser event count one, Workbench launch count one, and
|
||
surface count one.
|
||
Two events indicate duplicate production; one event with two launches
|
||
indicates duplicate routing or subscription; one launch with two surfaces
|
||
indicates a Workbench materialization race. Two real `window.open` requests
|
||
must remain two independent launches even when their URLs are equal.
|
||
The Electron integration fixture covers `did-attach-webview` followed by
|
||
`registerGuest`, installs the real Workspace App preload, and uses different
|
||
loopback origins for the guest and popup target. It then covers blank links,
|
||
internal blank links, `window.open` return semantics, external blank links,
|
||
external `window.open`, GET forms, deferred-popup rejection, and POST
|
||
rejection. Its owner renderer runs the real
|
||
workspace Browser event service, launch coordinator, presenter, and public
|
||
Workbench host with the production Browser multi-instance launch handler, so
|
||
one process asserts callback, Browser event, launch, materialized surface,
|
||
rejection notification, and denied native-child counts. The package boundary
|
||
test separately asserts that guest attachment installs one stable Electron
|
||
handler.
|
||
- References:
|
||
[workspaceAppWindowOpen.ts](../../../apps/desktop/src/main/ipc/workspaceAppWindowOpen.ts)
|
||
[workspaceBrowserService.ts](../../../apps/desktop/src/renderer/src/features/workspace-workbench/services/internal/workspaceBrowserService.ts)
|
||
[workbenchWorkspaceBrowserPresenter.ts](../../../apps/desktop/src/renderer/src/features/workspace-workbench/services/workbenchWorkspaceBrowserPresenter.ts)
|
||
|
||
### Agent opening several pages repeatedly steals workspace focus
|
||
|
||
- Symptom:
|
||
One Agent Turn asks to open several URLs. Every page is created successfully,
|
||
but each `new_page` result reveals and focuses the workspace again, producing
|
||
repeated foreground jumps during the same response.
|
||
- Quick checks:
|
||
Confirm the calls carry the same Agent session and persisted active Turn ID.
|
||
Separately count `Browser automation host activated` logs and workspace
|
||
Browser surface-focus requests. One host-activation log with several visible
|
||
Browser switches means the renderer reveal path is repeating even though
|
||
Main's window activation is already deduplicated.
|
||
- Root cause:
|
||
There are two foreground effects: Desktop Main activates the owning Electron
|
||
window, while the renderer focuses or opens the Browser surface before
|
||
creating a tab. Deduplicating only Main's post-create activation still lets
|
||
every renderer create request switch the workspace or standalone Agent panel
|
||
back to Browser.
|
||
- Fix:
|
||
Resolve the existing persisted active Turn in the daemon Browser CLI adapter,
|
||
carry it opaquely through BrowserNode automation, and keep the reveal policy
|
||
in Desktop Main. Mark only the first create request for each workspace, Agent
|
||
session, and Turn as revealable. The renderer must still create and select
|
||
every requested tab, but it focuses the workspace Browser surface or opens the
|
||
standalone Browser panel only when that flag is set. Bound the remembered
|
||
reveal keys and preserve the previous behavior when no exact Turn identity is
|
||
available.
|
||
- Validation:
|
||
Issue three concurrent create requests for one Turn and assert that all three
|
||
pages are requested with reveal flags `true`, `false`, `false` while the host
|
||
activates once. Assert the workspace and standalone renderer handlers do not
|
||
focus/open their Browser surface for `reveal=false`. Then issue a create for a
|
||
different Turn and assert it reveals again. Also cover turnless/manual
|
||
requests, BrowserNode transport parsing, and daemon active-Turn propagation.
|
||
- References:
|
||
[browserAutomationCoordinator.ts](../../../apps/desktop/src/main/ipc/browserAutomationCoordinator.ts)
|
||
[provider.go](../../../services/tuttid/service/cli/providers/browser/provider.go)
|
||
[automationRegistry.ts](../../../packages/browser/workbench-node/src/electron-main/automationRegistry.ts)
|
||
|
||
### Standalone Agent Browser Node is blank and never attaches a guest
|
||
|
||
- Symptom:
|
||
The standalone Agent window opens its Browser sidebar with the expected
|
||
title and panel background, but no page, error card, or Browser Node guest
|
||
appears. Desktop logs contain no `Browser Node webview will attach` entry for
|
||
the standalone browser node.
|
||
- Quick checks:
|
||
Inspect `window.tutti.browser` in the `view=agent` renderer before debugging
|
||
BrowserNode lifecycle or network access. Compare the preload route gate for
|
||
`view=agent` with `view=workspace`. An absent browser API explains a panel
|
||
that renders only host chrome and never reaches Electron guest attachment.
|
||
- Root cause:
|
||
The desktop preload exposed browser and workspace-app bridges only when the
|
||
renderer query used `view=workspace`. Standalone Agent windows use
|
||
`view=agent`, so their renderer received no `DesktopBrowserApi`; the sidebar
|
||
correctly reserved panel space but had no host API with which to activate or
|
||
register a `<webview>` guest.
|
||
- Fix:
|
||
Treat both `workspace` and `agent` as workspace surfaces in the preload route
|
||
gate. Keep dashboard and unrelated window routes excluded. Because preload
|
||
code is loaded when the Electron renderer is created, restart the Electron
|
||
process after changing this gate; renderer HMR is insufficient.
|
||
- Validation:
|
||
Unit-test the route predicate for `workspace`, `agent`, `dashboard`, and an
|
||
absent view. Run the desktop typecheck, Electron runtime-boundary check, and
|
||
desktop build. Confirm the preload remains a self-contained `index.cjs`, then
|
||
open the Agent Browser panel and verify desktop logs record the shared
|
||
Browser Node partition attaching with the browser guest preload.
|
||
- References:
|
||
[main.ts](../../../apps/desktop/src/preload/entries/main.ts)
|
||
[workspaceSurfacePreload.ts](../../../apps/desktop/src/preload/entries/workspaceSurfacePreload.ts)
|
||
[StandaloneAgentToolSidebar.tsx](../../../apps/desktop/src/renderer/src/features/workspace-workbench/ui/StandaloneAgentToolSidebar.tsx)
|
||
|
||
### `/browser` with adjacent CJK text reaches the provider as an unknown ACP command
|
||
|
||
- Symptom:
|
||
Typing `/browser打开百度` or `/computer点击确认` returns a provider error such
|
||
as `Unknown ACP command`, while the equivalent command with a space works.
|
||
The behavior can appear intermittent because selecting the Composer palette
|
||
entry inserts a canonical command token with a trailing space, whereas
|
||
directly typed text may not contain that boundary.
|
||
- Quick checks:
|
||
Compare the submitted user prompt with the provider's `session/prompt` input.
|
||
If the raw slash text reaches ACP unchanged and its byte length matches the
|
||
exact no-space draft, the local capability rewrite did not run. This is
|
||
distinct from Browser Node launch, attachment, and authorization failures.
|
||
- Root cause:
|
||
The local browser/computer capability parser previously treated the complete
|
||
non-whitespace token as the command name. Adjacent CJK arguments therefore
|
||
changed `browser` into the unknown name `browser打开百度`, bypassing the
|
||
browser-use handoff and exposing the raw text to providers with native slash
|
||
command parsing.
|
||
- Fix:
|
||
Recognize an adjacent suffix as capability arguments when it begins outside
|
||
the ASCII command-name character set. Preserve exact matching for ASCII
|
||
command continuations so strings such as `/browsering` and `/computer2` do
|
||
not become local capability commands. Keep this logic provider-neutral and
|
||
normalize the visible prompt to include the canonical separating space.
|
||
- Validation:
|
||
Cover English and localized browser/computer aliases with both spaced and
|
||
adjacent CJK arguments, plus negative ASCII-prefix cases. At the Composer
|
||
policy boundary, verify the draft is rewritten to the injected skill prompt
|
||
and carries the required capability settings patch instead of reaching ACP
|
||
as a raw slash command.
|
||
- References:
|
||
[agentCapabilityUseSubmit.ts](../../../packages/agent/gui/agent-gui/agentGuiNode/model/agentCapabilityUseSubmit.ts)
|
||
[agentSlashCommandProviderPolicy.ts](../../../packages/agent/gui/agent-gui/agentGuiNode/model/agentSlashCommandProviderPolicy.ts)
|
||
|
||
### In-app Browser new-page fails to attach for every provider
|
||
|
||
- Symptom:
|
||
`/browser` fails for Tutti Agent, Codex, Kimi Code, Claude Code, or another
|
||
Agent provider. `tutti browser new-page` returns `In-app Browser page did not
|
||
attach: browser:...:tab:1`, while `list-pages` remains empty. Desktop logs
|
||
show the automation server listening and the workspace renderer returning a
|
||
stable node id, but never show that node registering as a Browser automation
|
||
target.
|
||
- Quick checks:
|
||
Confirm the session advertises browser use and the slash command was rewritten
|
||
to the browser-use skill before debugging command discovery. If `new_page`
|
||
reaches the desktop host and returns a node id, inspect that node's initial
|
||
lifecycle and URL. Browser automation intentionally starts at `cold` and
|
||
`about:blank`; the creation path must carry an explicit cold-materialization
|
||
intent so the guest exists before the registry can attach request interception
|
||
and navigate.
|
||
- Root cause:
|
||
All Agent providers use the same BrowserNode automation authority.
|
||
`new_page` deliberately creates an `about:blank` tab in the full workspace
|
||
Browser before enabling its CDP request guard. Treating every cold blank page
|
||
as a home surface suppresses the `<webview>` guest, so the automation registry
|
||
can never observe the node id returned by the renderer. The request then
|
||
times out identically for every provider.
|
||
- Fix:
|
||
Materialize a cold Browser Node guest only when the automation creation path
|
||
marks that tab with the explicit materialization intent. Keep ordinary cold
|
||
tabs guest-free even though workspace Browser tabs also carry automation
|
||
target identity. Do not bypass the guarded `about:blank` sequence or navigate
|
||
before request interception is enabled.
|
||
- Validation:
|
||
Assert that an explicitly materialized cold Browser Node renders a webview
|
||
while an ordinary automatable cold tab remains guest-free. Run the Browser
|
||
Node package tests and the
|
||
changed-aware repository checks. In a running desktop, execute
|
||
`tutti browser new-page --url https://example.com` from sessions belonging to
|
||
multiple providers, verify the full workspace Browser appears with each page
|
||
in `list-pages`, and close the temporary pages.
|
||
- References:
|
||
[automationRegistry.ts](../../../packages/browser/workbench-node/src/electron-main/automationRegistry.ts)
|
||
[webviewController.ts](../../../packages/browser/workbench-node/src/core/webviewController.ts)
|
||
[workspaceBrowserService.ts](../../../apps/desktop/src/renderer/src/features/workspace-workbench/services/internal/workspaceBrowserService.ts)
|
||
|
||
### Agent reports a loaded page but the full workspace Browser is not visible
|
||
|
||
- Symptom:
|
||
An Agent reports that a page opened successfully, and `snapshot` or
|
||
`list-pages` returns the expected title and URL, but the full workspace
|
||
Browser does not come forward. Desktop logs show a Browser Node guest loading
|
||
the requested URL; they may even show `Browser automation host activated`
|
||
while the user still sees only the Agent conversation.
|
||
- Quick checks:
|
||
Treat a successful snapshot as proof that the guest exists, not that its
|
||
owner window is visible. Confirm `new_page` requested `surfaceRole=user`, the
|
||
workspace renderer focused or launched the preferred Browser node, and Main
|
||
activated the exact workspace window that returned the created tab id.
|
||
- Root cause:
|
||
Visibility has three independent gates. Page creation must route to the User
|
||
Browser rather than the embedded Agent Browser, the workspace renderer must
|
||
restore and focus the Browser node, and Main must reveal the exact owning
|
||
workspace window. Missing any gate lets an Agent inspect a real loaded page
|
||
while the user sees no full Browser surface.
|
||
- Fix:
|
||
Keep Agent session identity as the automation lease owner, but create the tab
|
||
on `surfaceRole=user`. Focus or launch the exact full Browser node before
|
||
responding, then reveal and focus its workspace window after creation
|
||
succeeds. Do not activate windows for metadata reads, screenshots, select,
|
||
close, or performance-headless runs.
|
||
- Validation:
|
||
Test that Agent-owned creation is sent to a User Browser host, the workspace
|
||
renderer focuses the preferred Browser node or launches the first one, and
|
||
Main activates the responding workspace window. In a running Desktop, create
|
||
a page through the CLI, verify a large Browser page comes forward with the
|
||
loaded URL, and confirm the log records `Browser automation host activated`.
|
||
- References:
|
||
[browserAutomationCoordinator.ts](../../../apps/desktop/src/main/ipc/browserAutomationCoordinator.ts)
|
||
[browser.ts](../../../apps/desktop/src/main/ipc/browser.ts)
|
||
[workspaceBrowserService.ts](../../../apps/desktop/src/renderer/src/features/workspace-workbench/services/internal/workspaceBrowserService.ts)
|
||
[WorkspaceWorkbench.tsx](../../../apps/desktop/src/renderer/src/features/workspace-workbench/ui/WorkspaceWorkbench.tsx)
|
||
|
||
### Browser Node action finds a webview but page injection does nothing
|
||
|
||
- Symptom:
|
||
A Browser Node toolbar action is visible and clickable, but moving the pointer
|
||
over the loaded page produces no expected guest-page behavior. Desktop logs
|
||
may report `The WebView must be attached to the DOM and the dom-ready event
|
||
emitted before this method can be called`, especially after HMR, navigation,
|
||
or panel remount.
|
||
- Quick checks:
|
||
Do not treat a matching `<webview>` DOM element or a visibly rendered page as
|
||
proof that Electron methods are callable. Call `getWebContentsId()` inside a
|
||
`try` block and confirm it returns a finite id. Check whether the action found
|
||
a detached element, ran before `dom-ready`, or retained a stale element while
|
||
React cleanup and BrowserNode guest teardown raced.
|
||
- Root cause:
|
||
Electron exposes the webview element before its guest method bridge is ready,
|
||
and detaches that bridge before React passive cleanup necessarily runs. Direct
|
||
DOM lookup followed immediately by `executeJavaScript()` therefore races the
|
||
BrowserNode lifecycle. The method can also throw synchronously before it
|
||
returns a Promise, so appending `.catch()` alone does not protect cleanup.
|
||
- Fix:
|
||
Reuse BrowserNode's guest lifecycle rather than creating a second owner. Before
|
||
guest script execution, require a connected webview with a readable finite
|
||
web contents id; otherwise wait for its `dom-ready` event with a bounded
|
||
timeout. Treat cancellation during navigation or unmount as best-effort and
|
||
guard the full method call with `try`/`catch`, including synchronous throws.
|
||
For the element selector specifically, keep the selection session independent
|
||
from one guest: consume BrowserNode's active-webview context, move the
|
||
selector to the newly active webview, and re-arm it after navigation
|
||
`dom-ready`. Increment an attempt token whenever the target changes so a late
|
||
result from the previous page cannot finish the new page's selection.
|
||
- Validation:
|
||
Test delayed `dom-ready`, detached webviews, unmount cancellation, switching
|
||
tabs while selecting, and navigating the active tab while selecting. Run the
|
||
desktop typecheck, changed-aware checks, and production build. Confirm the
|
||
guest action is bundled with the standalone Agent browser adapter, then reload
|
||
the standalone Agent window before a manual page-selection smoke test.
|
||
- References:
|
||
[browserElementWebview.ts](../../../packages/agent/gui/workbench/browser-element-context/browserElementWebview.ts)
|
||
[BrowserElementContextAction.tsx](../../../packages/agent/gui/workbench/browser-element-context/BrowserElementContextAction.tsx)
|
||
[webviewController.ts](../../../packages/browser/workbench-node/src/core/webviewController.ts)
|
||
|
||
### Hidden Browser Node webview covers another panel
|
||
|
||
- Symptom:
|
||
After switching from Browser Node to another panel in the same layout region,
|
||
the new panel title or sidebar appears but the previous web page still covers
|
||
part of its content. The panel selection state correctly identifies only the
|
||
new panel as active. The same root cause can make a Browser Node header menu
|
||
or dialog appear unresponsive: its trigger changes state, but the open Portal
|
||
is visually covered by the guest page.
|
||
- Quick checks:
|
||
Inspect the mounted `BrowserNode` and its `<webview>` in DevTools. If the
|
||
parent panel has `visibility: hidden`, `display: none`, or an inactive class
|
||
but `BrowserNode` still receives `hidden={false}`, treat the guest surface as
|
||
the likely overlay before changing the panel reducer.
|
||
- Root cause:
|
||
Electron webviews are guest surfaces with compositing behavior that cannot be
|
||
treated as ordinary descendant DOM for visibility coordination. Keeping a
|
||
Browser Node mounted preserves its local session, but hiding only an ancestor
|
||
panel can leave the guest surface visible above the newly active sibling.
|
||
- Fix:
|
||
Keep one active panel id for tools that share the same region. Pass that
|
||
active state into every mounted Browser Node through its `hidden` prop, while
|
||
retaining the mounted component when session preservation is required. Keep
|
||
the App Center catalog and every workspace app listed in the persisted
|
||
`openAppIds` tab state as mounted sibling layers: selecting the permanent
|
||
catalog tab clears `openAppId` but must not remove an app's Browser Node, and
|
||
selecting another app tab must not replace the previous app's keyed Browser
|
||
Node. Closing a tab removes its id from `openAppIds` and intentionally releases
|
||
that guest. Give each inline app a stable app-specific node id so Browser Node
|
||
controllers and Electron guests cannot be rebound to a different app. A ready
|
||
catalog snapshot may also close tabs for apps confirmed unavailable; loading
|
||
or reconnecting snapshots are not proof that an app disappeared. Inactive app
|
||
layers need both non-interactive DOM
|
||
visibility and `hidden={true}` on `BrowserNode`, because ancestor visibility
|
||
alone is insufficient for Electron guest compositing. Do not add an explicit
|
||
`visibility: visible` utility to the active child layer: CSS descendants can
|
||
override an inactive parent panel's inherited `visibility: hidden` and leak
|
||
the retained app or catalog over a newly selected sibling panel. Let active
|
||
layers inherit visibility from their parent, and apply `invisible` only to
|
||
inactive layers. Keep
|
||
tools in separate layout regions, such as a bottom terminal tray, on an
|
||
independent visibility state. For Browser Node-owned dialogs, track open
|
||
overlays by node id and mark the registered webview invisible until all modal
|
||
overlay owners close; do not unmount the webview or discard its session.
|
||
Render header menus inline through one `MenuSurface` positioned from the
|
||
browser header, and do not hide the webview for that inline menu. Keep nested
|
||
action views inside the same surface instead of opening Radix or
|
||
viewport-menu Portals above the guest. Portaled controls opened from a dialog,
|
||
such as `SelectContent`, must use the `--z-dialog-popover` semantic layer. The
|
||
ordinary `--z-popover` layer renders behind dialog content and makes the
|
||
control appear unresponsive even though its open state changed correctly.
|
||
- Validation:
|
||
Cover every switch among panels in the shared region, verify the inactive
|
||
Browser Node receives `hidden={true}`, and verify an independently placed
|
||
terminal remains open throughout the same switches. For App Center, open two
|
||
apps, switch through their tabs and the permanent catalog tab, and reopen both;
|
||
page state and any running in-page Agent must continue while inactive Browser
|
||
Nodes stay hidden. Close the active and inactive app tabs in turn and verify
|
||
the adjacent/catalog fallback plus guest release. Also open the Browser Node
|
||
overflow menu, its submenus, settings
|
||
dialog, and clear-data confirmation above a loaded guest page; verify the
|
||
webview returns after each overlay closes. Renderer-only visibility changes
|
||
can use HMR; preload or Electron-main changes still require a process restart.
|
||
- References:
|
||
[BrowserNode.tsx](../../../packages/browser/workbench-node/src/react/BrowserNode.tsx)
|
||
[browserNodeHostOverlayStore.ts](../../../packages/browser/workbench-node/src/react/browserNodeHostOverlayStore.ts)
|
||
[dropdown-menu.tsx](../../../packages/ui/system/src/components/dropdown-menu/dropdown-menu.tsx)
|
||
[StandaloneAgentToolSidebar.tsx](../../../apps/desktop/src/renderer/src/features/workspace-workbench/ui/StandaloneAgentToolSidebar.tsx)
|
||
|
||
### IME composition leaks native input into xterm terminals
|
||
|
||
- Symptom:
|
||
Chinese, Japanese, or Korean text appears in a workspace terminal, but using
|
||
Space or Enter to commit the candidate sends extra or strange input into the
|
||
PTY, leaving the shell prompt or terminal display in an unexpected state.
|
||
- Quick checks:
|
||
Inspect custom `attachCustomKeyEventHandler` logic before suspecting the PTY
|
||
or websocket encoding. In xterm 6, the custom key handler runs before
|
||
`CompositionHelper.keydown`; returning `false` skips that xterm path but does
|
||
not automatically prevent the browser's hidden textarea from receiving native
|
||
input.
|
||
- Root cause:
|
||
A guard that suppresses a post-composition commit key by only returning
|
||
`false` can still allow the browser default action to mutate xterm's textarea.
|
||
The later xterm `input` or delayed composition send can then forward polluted
|
||
textarea content as terminal input.
|
||
- Fix:
|
||
During active composition, do not call `preventDefault`; the browser and IME
|
||
need native composition behavior. For post-composition commit-key suppression,
|
||
call `preventDefault` and `stopPropagation` before returning `false`, and keep
|
||
the short suppression window open for repeated native key events.
|
||
- Validation:
|
||
Add unit coverage that active composition is not prevented, post-composition
|
||
commit keys are prevented, and repeated native key events within the window
|
||
stay suppressed. Manually verify Chinese IME candidate commit with Space and
|
||
Enter in the workspace terminal.
|
||
- References:
|
||
[terminalImeInputGuard.ts](../../../packages/workspace/terminal/src/react/terminalImeInputGuard.ts)
|
||
[terminalSurfaceRuntime.ts](../../../packages/workspace/terminal/src/react/terminalSurfaceRuntime.ts)
|
||
|
||
### Chinese input renders replacement and control characters in workspace terminals
|
||
|
||
- Symptom:
|
||
Chinese input reaches a local workspace terminal, but the shell prompt shows
|
||
replacement glyphs or control-byte markers such as `<0095>`. ASCII input and
|
||
commands continue to work, which can make the failure look like an xterm IME
|
||
composition bug.
|
||
- Quick checks:
|
||
Run `locale` or `locale charmap` inside a newly created terminal. If
|
||
`LC_CTYPE` resolves to `C` and the character map is not UTF-8, inspect the
|
||
desktop and `tuttid` process environments for `LC_ALL`, `LC_CTYPE`, and
|
||
`LANG` before changing xterm key handlers or terminal transport encoding.
|
||
- Root cause:
|
||
Finder-launched macOS applications commonly start without locale variables.
|
||
The daemon inherited that environment and spawned the interactive shell
|
||
without a character-type locale, so zsh interpreted UTF-8 IME bytes under the
|
||
single-byte `C` locale and rendered invalid or control characters.
|
||
- Fix:
|
||
When all locale variables are absent or effectively empty on macOS, append
|
||
`LC_CTYPE=UTF-8` to the terminal child environment. Preserve any explicit
|
||
`LC_ALL`, `LC_CTYPE`, or `LANG` value. Restrict the fallback to the character
|
||
type so message language, sorting, dates, and other locale categories do not
|
||
change.
|
||
- Validation:
|
||
Unit-cover missing, empty, explicit, and non-macOS environment cases. Start a
|
||
real macOS zsh PTY with empty locale variables and assert `locale charmap`
|
||
reports `UTF-8`, then manually enter Chinese text in a newly created terminal.
|
||
Existing terminal processes retain their original environment and must be
|
||
replaced for the fix to take effect.
|
||
- References:
|
||
[terminal_helpers.go](../../../services/tuttid/service/workspace/terminal_helpers.go)
|
||
[terminal_helpers_test.go](../../../services/tuttid/service/workspace/terminal_helpers_test.go)
|
||
[terminal_test.go](../../../services/tuttid/service/workspace/terminal_test.go)
|
||
|
||
### Post-composition suppression window swallows real terminal input
|
||
|
||
- Symptom:
|
||
After committing Chinese IME text in a workspace terminal, the next quick
|
||
keystroke is intermittently lost: Enter pressed right after the candidate
|
||
commits does not execute the command (it must be pressed twice), fast typing
|
||
drops the first letter of the next word, or a full-width punctuation mark
|
||
typed immediately after a commit never reaches the PTY.
|
||
- Quick checks:
|
||
Reproduce with fast input — commit a candidate with Space, then press Enter
|
||
or type the next character within ~80ms. Losses that disappear when typing
|
||
slowly point at the IME guard's post-composition window, not the PTY.
|
||
- Root cause:
|
||
The guard suppressed every unmodified key for a fixed window after
|
||
`compositionend` to swallow ghost commit-key events. Only keys that can
|
||
commit a candidate (Enter, Escape, Space, digit selection keys) can replay
|
||
after `compositionend`; blanket suppression also swallowed genuine next
|
||
keystrokes, and blocking keyCode 229 keydowns kept xterm's
|
||
`CompositionHelper._handleAnyTextareaChanges` from forwarding IME
|
||
punctuation entered right after a commit.
|
||
- Fix:
|
||
Inside the window, suppress only commit-capable keys (Enter, Escape, Space,
|
||
digits); let all other keys through so xterm's own keyCode 229 handling
|
||
still runs. Ghost events replay before the physical key is released, so
|
||
close the window as soon as a keyup arrives outside composition — any later
|
||
keydown is genuine user input, including genuine digits.
|
||
- Validation:
|
||
Unit-cover letters and `Process` keys passing through the window, keyup
|
||
closing the window so a repeated Enter or digit is processed, and commit
|
||
keys (including digits) staying suppressed. Manually commit with Space then
|
||
immediately press Enter, select a candidate with a digit key, and type
|
||
full-width punctuation right after a commit.
|
||
- References:
|
||
[terminalImeInputGuard.ts](../../../packages/workspace/terminal/src/react/terminalImeInputGuard.ts)
|
||
|
||
### Published package runtime asset 404 because the consumer bundler never saw the file
|
||
|
||
- Symptom:
|
||
An external consumer installs a public `@tutti-os/*` package, uses the
|
||
package, and gets a browser or renderer 404 for an icon or image such as
|
||
`dist/assets/...`. The same feature often works inside this monorepo because
|
||
workspace source resolution or local build layout hides the packaging
|
||
problem.
|
||
In Vite development mode the failing URL may instead point at
|
||
`node_modules/.vite/deps/assets/...`: dependency prebundling moved the
|
||
JavaScript module, then a preserved `new URL("./assets/...", import.meta.url)`
|
||
resolved relative to the optimizer cache.
|
||
A browser-only correction can surface as `Unknown file extension ".png"` in
|
||
Vitest when the test runner externalizes the published dependency and Node
|
||
evaluates its asset import directly.
|
||
- Quick checks:
|
||
If the failing package entrypoint renders a package-local image or icon,
|
||
inspect whether the main runtime entrypoint still imports that asset directly
|
||
instead of leaving it to an explicit asset subpath such as
|
||
`./assets/workspace-dock-website.png`.
|
||
Run `pnpm release:pack:check` and confirm the packed tarball includes the
|
||
exported asset file under `dist/assets/...`.
|
||
Inspect the built `dist` entrypoint and confirm the main runtime code no
|
||
longer uses a module-relative asset URL. If the runtime intentionally imports
|
||
the asset, verify the public export has both a browser asset target and a
|
||
Node-executable target.
|
||
- Root cause:
|
||
The public runtime entrypoint owned a default asset dependency instead of
|
||
exposing that asset as an explicit public subpath. The packed npm artifact
|
||
either did not ship the matching file layout or forced every consumer to pay
|
||
the asset cost even when the feature was unused.
|
||
A related failure occurs when a published bundle preserves a module-relative
|
||
`new URL(...)`: consumer dependency optimization can relocate that bundle
|
||
independently from its adjacent asset.
|
||
- Fix:
|
||
Move the image or icon out of the main runtime entrypoint and export it
|
||
through an explicit package asset subpath such as
|
||
`./assets/workspace-dock-website.png`.
|
||
Let the business consumer import that asset only when it needs the default
|
||
visual, and keep the package build rule that copies the asset into the packed
|
||
`dist/assets` directory.
|
||
When the package runtime owns an always-available default icon, prefer a
|
||
code-owned UI-system SVG component so the runtime does not import an image at
|
||
all. Conditional asset exports are not sufficient for this case: a
|
||
browser-conditioned test environment can select the image target and then
|
||
externalize the package for Node execution, which still fails on `.png`.
|
||
Keep explicit public asset subpaths only for browser consumers that knowingly
|
||
opt into the artwork. Do not require every consumer to add a test alias for
|
||
the published package.
|
||
Apply the same rule to every public runtime subpath in the package, not just
|
||
the first failing icon.
|
||
- Validation:
|
||
Build the affected package, inspect the built runtime entrypoint for the
|
||
absence of the old asset dependency, and rerun `pnpm release:pack:check`.
|
||
Import any intentionally supported packed asset subpath with Node and run a
|
||
real Vite dependency-prebundle fixture. The optimized root runtime must
|
||
contain the code-owned fallback icon and no fallback image dependency.
|
||
If the package is consumed by desktop renderer code in this repo, also run
|
||
the relevant desktop build to confirm the consumer bundler copies or emits
|
||
the asset only when the business import is present.
|
||
- References:
|
||
[docs/conventions/npm-package-release.md](../npm-package-release.md)
|
||
[packages/browser/workbench-node/package.json](../../../packages/browser/workbench-node/package.json)
|
||
[packages/browser/workbench-node/src/workbench/index.ts](../../../packages/browser/workbench-node/src/workbench/index.ts)
|
||
[packages/workspace/issue-manager/package.json](../../../packages/workspace/issue-manager/package.json)
|
||
[packages/workspace/issue-manager/src/workbench/index.ts](../../../packages/workspace/issue-manager/src/workbench/index.ts)
|
||
|
||
### New release CDN namespace returns an S3 403
|
||
|
||
- Symptom:
|
||
Release artifacts upload successfully and `s3api head-object` finds them,
|
||
but the corresponding CloudFront URL returns HTTP 403 with
|
||
`server: AmazonS3` and `x-cache: Error from cloudfront`.
|
||
- Quick checks:
|
||
Compare the requested path with the distribution's ordered cache behaviors,
|
||
identify the selected origin, and inspect the origin bucket policy for a
|
||
matching `s3:GetObject` resource prefix. Do not treat a successful S3 upload
|
||
or invalidation as proof that the CDN route exists.
|
||
- Root cause:
|
||
The new release namespace was uploaded before its CloudFront path behavior
|
||
and S3 read policy were provisioned. The request fell through to an unrelated
|
||
default origin, which correctly returned AccessDenied.
|
||
- Fix:
|
||
Add a read-only cache behavior for the namespace that targets the intended S3
|
||
origin, append the narrow bucket-policy resource prefix, wait for the
|
||
distribution deployment, and invalidate the new namespace. Preserve every
|
||
unrelated distribution behavior and use the current distribution ETag when
|
||
updating it.
|
||
- Validation:
|
||
Download mutable index metadata, immutable release metadata, and the artifact
|
||
from the public CDN. Require HTTP 200 and rerun signature, SHA-256, and byte
|
||
size verification against those downloaded files.
|
||
- References:
|
||
[Agent Extensions](../../architecture/agent-extensions.md) and the concrete
|
||
Agent repository's release workflow.
|
||
|
||
### Browser Node focus pings miss iframe-hosted editors
|
||
|
||
- Symptom:
|
||
Clicking or typing inside a workspace app selects text or edits content, but
|
||
the owning Browser Node does not become the active node. This commonly shows
|
||
up in rich document editors that render the editable surface inside a
|
||
same-origin `iframe` or `srcdoc` frame.
|
||
- Quick checks:
|
||
Inspect whether the app portals or mounts its editor into an iframe document.
|
||
If the top-level workspace app preload listens on `window.document` only, the
|
||
host will not receive pointer, focus, or keyboard pings from that child frame.
|
||
- Root cause:
|
||
DOM events do not bubble from iframe documents to the parent document. Electron
|
||
webview preloads also do not run in subframes unless the host enables
|
||
`nodeIntegrationInSubFrames`, so iframe-hosted editors can interact normally
|
||
while the Browser Node focus bridge stays silent.
|
||
- Fix:
|
||
Enable subframe preload execution only for host-controlled Browser Node or
|
||
workspace app guest preloads. Keep privileged workspace app bridges, such as
|
||
`tuttiExternal`, and behavior-changing guest logic, such as `_blank` link
|
||
interception, main-frame-only via `process.isMainFrame`. Install only passive
|
||
interaction forwarding in subframes.
|
||
- Validation:
|
||
Run Browser Node and desktop preload tests, desktop typecheck, and the desktop
|
||
build. For workspace app preloads, inspect the built preload output so the
|
||
guest files remain self-contained.
|
||
- References:
|
||
[webviewSecurity.ts](../../../packages/browser/workbench-node/src/electron-main/webviewSecurity.ts)
|
||
[workspaceApp.ts](../../../apps/desktop/src/preload/entries/workspaceApp.ts)
|
||
[workspaceAppInteractionForwarding.ts](../../../apps/desktop/src/preload/entries/workspaceAppInteractionForwarding.ts)
|