Change Maple Agent Mode

Change Maple Agent Mode

Work from the Maple repository root. Read root AGENTS.md and apps/maple-research/AGENTS.md, the current source, nearby tests, and relevant docs before editing. Treat apps/maple-research/frontend/src-tauri/Cargo.toml, apps/maple-research/frontend/src-tauri/Cargo.lock, the implementation, and test suite as authoritative when historical prose disagrees.

Root AGENTS.md owns shared policy; apps/maple-research/AGENTS.md owns app setup and runtime conventions. Use $validate-maple for complete CI-equivalent, packaged, or cross-platform validation, and $review-maple-security when a change touches credentials, authorization, privileged tools, process execution, local IPC, or another trust boundary.

Do not commit, push, open a PR, merge, release, or clean unrelated work unless the user explicitly requests it.

Understand the Runtime Before Changing It

Keep Maple's two inference paths distinct:

• Research chat is a browser-capable React path. UnifiedChat.tsx uses the OpenAI JavaScript client with @mapleai/sdk's authenticated and encrypted aiCustomFetch, targeting OpenSecret's Conversations and Responses APIs.
• Agent Mode is desktop-only. AgentMode.tsx calls typed frontend services, which invoke Tauri commands and receive agent-event envelopes. Native Rust owns MapleAgentService, the embedded Goose managers and local sessions, Maple's provider, developer tools, permissions, and cancellation. MapleProvider sends encrypted OpenSecret SDK requests to /v1/chat/completions.
• ACP is a secondary local adapter over the same MapleAgentService. It must not initialize a second Goose runtime or call through the Tauri adapter.
• The local OpenAI-compatible proxy is a separate user-facing feature. Neither Research chat nor Agent Mode should silently route through it.
• Agent Mode, Goose, native OpenSecret auth, MCP, and ACP compile only for desktop. Mobile retains shared React functionality and selected native facilities such as document extraction, not Agent Mode.

Maple locally persists Agent tasks, project configuration, MCP snapshots, and Goose session history under an opaque account scope. OpenSecret remains authoritative for account identity, authentication, encrypted inference, model/backend policy, and web search or extraction. Do not confuse local Agent history with server-persisted Research conversations.

Put Changes at the Owning Boundary

Use these seams:

• apps/maple-research/frontend/src/components/AgentMode.tsx and apps/maple-research/frontend/src/components/agent/: presentation, interaction state, accessible controls, and projection of native events. Do not enforce security only here.
• apps/maple-research/frontend/src/services/agentRuntimeService.ts: typed Tauri commands/events, user-operation fencing, and logout/account-transition coordination.
• apps/maple-research/frontend/src/services/mapleApiAuthService.ts: browser/native credential reconciliation. Do not copy this logic into components.
• apps/maple-research/frontend/src-tauri/src/agent_tauri.rs: the stable Desktop command and event adapter. Keep it thin.
• apps/maple-research/frontend/src-tauri/src/agent_host.rs: operations spanning the core runtime and ACP, including stop, restart, clear, exit, and update shutdown.
• apps/maple-research/frontend/src-tauri/src/agent.rs: transport-neutral Agent domain state, account handles, Goose/session orchestration, persistence, run ownership, timelines, MCP and skills attachment, and permission routing. Do not import Tauri or ACP protocol types into this core.
• apps/maple-research/frontend/src-tauri/src/agent/provider.rs: Goose-provider request construction, encrypted inference transport, streaming, bounded error handling, retry policy, and cancellation.
• apps/maple-research/frontend/src-tauri/src/maple_api.rs: account-scoped native OpenSecret SDK sessions, backend identity validation, atomic credential replacement, and refresh reconciliation.
• sdk/rust/: source for the Maple Rust SDK. Research selects a published version or local source through apps/maple-research/frontend/src-tauri/Cargo.toml and its lockfile. Follow the consumer version policy and verify the resolved graph before claiming an SDK source edit reaches Agent Mode; a registry-pinned build does not exercise that edit.
• apps/maple-research/frontend/src-tauri/src/agent/developer_tools.rs: Maple's privileged read, write, edit, image, shell, and backend web-tool implementations. Add privileged tools here rather than exposing an unmediated Goose tool path.
• apps/maple-research/frontend/src-tauri/src/agent/{shell_permission,web_permission,tool_context,web_tools}.rs: automatic policy, secret-bearing execution context, public-URL admission, provenance, and output bounds.
• apps/maple-research/frontend/src-tauri/src/agent/system_prompt.rs: the narrowly rebranded copy of the pinned Goose system prompt.
• apps/maple-research/frontend/src-tauri/src/agent_acp.rs: ACP framing, Unix socket ownership, connection/session leases, caller-owned permissions, and adapter-specific environment allowlists.

Put behavior in OpenSecret instead when it must be authoritative against a modified client, shared by multiple clients, durable across devices, or part of the public API, authentication, confidential-compute, model, provider, search, or extraction contract. Coordinate the open-source backend and the in-tree SDK under sdk/ rather than emulating missing enforcement in Maple.

Preserve Trust and Lifecycle Invariants

Account and credential isolation

• Bind every native operation to the requested user's opaque account scope and current handle generation. Reject stale handles and cross-account sessions.
• Validate candidate native credentials against the backend before publishing them. Preserve atomic replacement and prevent a late refresh from overwriting a newer browser or native token pair.
• Synchronize auth before authenticated Tauri calls. On logout or account switch, block new operations, drain Agent/ACP, then clear native auth and account-bound local proxy credentials.
• Never put OpenSecret access or refresh tokens into Goose configuration, prompts, tool arguments, child environments, logs, or error strings.

Runtime, session, and run lifecycle

• Keep one authoritative native runtime for the signed-in account. Serialize start, stop, restart, clear, exit, and update operations across Agent and ACP.
• Claim a session before changing its title, model, permission mode, extensions, or tool context. Reject concurrent mutation rather than racing it.
• Define ownership for every spawned task, listener, stream, permission request, cancellation token, and secret-bearing context. Ensure every terminal path cancels, joins, revokes, persists or repairs history, emits an authoritative terminal event, and removes active state in the intended order.
• Fence frontend async work by account, session, run, and revision/generation. Navigation may change the visible task but must not redirect an existing run's events.
• Preserve the session model lock after history exists. Treat a model change as a new task unless product requirements explicitly change that contract.
• Keep bounded event queues fail-loud. Never let Desktop or ACP backpressure Goose indefinitely or silently present a truncated stream as complete.

Permissions and privileged tools

• Keep Goose live in SmartApprove so every sensitive tool reaches Maple's policy boundary. Persist the user-facing Read only (smart_approve) or Allow all (auto) choice separately.
• Reset Maple's Goose permission file so read, shell, edit, write, read_image, web_search, and open_url route through ask_before; only load_skill is always allowed.
• Derive current policy per tool from its permission configuration, automatic handler, classifier, and executor. Distinguish always-allowed, automatic, classifier-approved, and caller-approved paths; do not generalize one tool's classifier or URL policy to another.
• Automatic policy may approve only explicitly defined operations. On a classifier-backed path, timeout, failure, or ambiguity falls back to caller approval; otherwise follow the explicit per-tool policy.
• Preserve one-shot, run-scoped permission capabilities. The calling surface owns unresolved permissions: Desktop for Desktop runs and ACP for ACP runs. Never expose one actionable request to both.
• Bound shell time and output. Treat process-group or job-object cleanup as best-effort containment of the current child tree, not a hard credential boundary. On normal cancellation, revocation, timeout, or overflow, revoke the context, request tree termination through the owned process-group or job handle, and reap the wrapped child. If hard non-survival is required, keep credentials out of arbitrary child environments.
• Treat paths, shell commands, MCP definitions, headers, environment values, model output, URLs, extracted pages, and tool results as untrusted. Revalidate at the native enforcing boundary.
• Admit open_url only for normalized public HTTPS URLs. Preserve private, loopback, link-local, metadata, credential-bearing, and malformed URL rejection, bounded output, per-session provenance, and explicit untrusted-evidence notices.

Skills, projects, MCP, and ACP

• Keep project roots canonical and account-scoped. Project removal, ordering, history, and trust decisions must not mutate another account or silently re-add a removed root.
• Load project instructions and skills only after the user trusts that canonical project. Keep the skills client transient so Goose cannot reconstruct it later with an untrusted real working directory.
• Validate and freeze MCP definitions into each session. Preserve reserved names, unsafe-environment rejection, header normalization, owner-only storage where supported, and the warning that obscured stored values are not encrypted at rest.
• Keep ACP disabled by default and Unix-only until its implementation changes. Require absolute admitted roots, owner-only socket access, bounded frames/connections/outbound work, exact session leases, and explicit environment allowlists. Revocation or disconnect must make captured tool context unusable.
• Never describe read_only ACP configuration as a sandbox. It is caller-mediated permission policy; a caller can still approve mutation.

Provider and privacy behavior

• Preserve authenticated encrypted transport through the OpenSecret SDK. MapleProvider must not own token storage or refresh.
• Retry only failures that are safe before the first successful streamed item. Do not repeat deterministic client failures or side effects speculatively.
• Keep parser errors, HTTP bodies, provider details, decrypted SSE data, prompts, tool results, and private file contents out of logs and user-facing error strings. Return bounded, categorized errors.
• Preserve cancellation through Goose, provider transport, SDK operations, tools, and terminal history repair.

Follow the Change Workflow

1. Inspect git status --short --branch, current SHA, origin/master, and the complete existing diff. Preserve unrelated work and do not switch branches over a dirty tree.
2. Trace the request through UI, frontend bridge, Tauri adapter, core service, Goose, provider/tools, persistence, and backend. Identify which boundaries do not need to change.
3. Write down the account owner, session owner, run owner, permission owner, cancellation path, persistence point, terminal event, and cleanup path for the proposed behavior before editing concurrent code.
4. Add or update the smallest transport-neutral core behavior first, then adapters/wire types, then UI projection. Keep adapters from reaching through one another.
5. Add regression tests for success plus stale account/session/run, cancellation, duplicate/concurrent calls, partial failure, restart/reload, and bounded-input behavior relevant to the change.
6. Update public docs when behavior or compatibility changes. Mark historical smoke evidence as historical and never copy an old dependency pin into current instructions.
7. Inspect the final diff for secret logging, unbounded data, bypassed permissions, detached tasks, stale completion, cross-account access, and behavior that belongs in OpenSecret.

For a Goose bump, obtain the exact revision from apps/maple-research/frontend/src-tauri/Cargo.toml, inspect that revision in a real git checkout, update apps/maple-research/frontend/src-tauri/Cargo.lock, and compare apps/maple-research/frontend/src-tauri/src/agent/system_prompt.rs byte-for-byte with the pinned Goose crates/goose/src/prompts/system.md. Only Maple's two identity lines may differ. Re-run the prompt-drift test and every affected provider, permission, tool, MCP, session, and lifecycle test. Do not reason from an unversioned source archive or current Goose main.

Run Targeted Tests

Run the smallest relevant frontend set without Bun's automatic dotenv loading:

nix develop --no-update-lock-file .#ci -c bash -c \
  'cd apps/maple-research/frontend && bun --no-env-file test ./src/components/AgentMode.test.ts'

Add only the service tests matching the changed boundary, such as runtime/auth lifecycle, operation fencing, timeline, models, MCP, project/session selection, or connection availability.

Run Rust tests by affected module while iterating:

nix develop --no-update-lock-file .#ci -c bash -c \
  'cd apps/maple-research/frontend/src-tauri && cargo test --locked "agent::provider::tests::"'

Replace the example filter with the affected module and add adjacent filters only when their boundary changed. Run the complete locked Rust suite before handing off a native change. For any Agent Mode change, also run formatting, linting, typechecking, and builds required by $validate-maple. Unit tests do not replace a real desktop smoke.