macOS alpha, 0.32.0-alpha.1

Moguri SDK and CLI

The importable SDK, its entrypoints and the moguri CLI.

Published unchanged from docs/sdk.md in Moguri's source repository at commit b686ddc (0.32.0-alpha.1). That repository isn't public yet, so references to files that only exist there appear as plain text with a dotted underline.

Moguri is one importable SDK, with terminal and desktop clients on top. The service is the only durable writer; the SDK exposes its typed commands, queries, sequenced events, optimistic revisions and cancellation. Electron does not own a second agent loop, settings store or provider connection.

Current source uses protocol 103 for owned reviewed-script Sandbox execution (not public yet), preserving protocol102's exact native candidate/private-root identities and protocol 101 for reviewed repository trust, isolated task defaults and recoverable output (not public yet). It preserves protocol100 script Inbox approval and protocol99 session Inbox and explicit skill-load evidence (not public yet), on top of genuine98 Local source admission and full-Env per-turn rewind (not public yet). The additive upgrade preserves the actual95/96/97/98 lineage, ciphertext, owners, receipts and all-role accounting. Root/React entrypoints remain browser-safe; service startup and execution stay in the explicit lazy Node entrypoint. Protocol 95 introduced the unified My Work inbox (not public yet). Its source/refresh/job/attention state is profile-owned and retained by the existing event authority. Genuine94 adds the inbox marker atomically; older healthy services require reviewed upgrade rather than silently omitting this API. Root/React imports remain browser-safe and Node GitHub execution stays explicit.

Repository trust and workflow defaults

const { preview } = await sdk.repositoryTrust.preview(projectId);
// Actual user reviews the exact Local root, existing source digests and exclusions.
await sdk.repositoryTrust.trust(preview);
const trust = sdk.repositoryTrust.get(projectId);
if (trust?.status === "trusted") await sdk.repositoryTrust.revoke(projectId, trust.revision);

const task = await sdk.sessions.create(projectId, "Isolated task");
const session = sdk.sessions.get(task.id!);
if (session?.workspaceId) await sdk.workspaces.wait(session.workspaceId);
// Explicit user opt-out for this new task only; never moves an existing session.
await sdk.sessions.create(projectId, "Attached checkout", undefined, undefined, "checkout");

Trust is actual-user authority over exact existing tracked script entrypoints, not model advice or execution permission. Its project-owned encrypted baseline survives session deletion. repository.trust_recorded stores monotonic approval/revocation; repository.script_reserved atomically retains each original source-bound model attempt before effects. New/changed/generated/ downloaded/package scripts and changed dependency inputs cannot inherit trust. Live validation binds the exact Local root/worktree, original Git common identity, profile/project, source bytes, dependency inputs and current policy. run_script({path, interpreter, args?}) is the trusted variant; callers cannot provide trust authority. The ordinary reviewed variant retains its original reviewId, digest/revision and one-attempt semantics. Both use the existing private-pipe source executor and normal approvals. Unsupported transports fail without fallback; entrypoint authority is not transitive-code confinement.

For new single-project Local Git tasks, worktree/change-set/job/session intent commits atomically. workspaceOrigin: "default-worktree" identifies that actual choice; explicit bindings/checkout opt-outs have their distinct origins. Never dispatch files, tools or consoles until the retained workspace is ready. Legacy sessions are not moved or relabelled; non-Git folders have no invented managed-worktree origin. Automatic multi-repository worktrees are not qualified: new Local Git groups refuse an implicit base-root fallback. Project preferences repo.workspaceMode and repo.pullRequests default to "worktree"/"draft" when absent. CLI session create --workspace-mode checkout opts out explicitly. First-party draft-PR guidance enters capture/sizing before admission; it does not grant GitHub writes, authentication or merge.

turn.recovery_entered binds one original unconfirmed partial result to its actual turn/step/call. The service restricts subsequent model tools and dispatch to read-only inspection; uncertainty and root quarantine remain retained. Only actual started Local command/script process ownership can carry tool.completed.cleanupConfirmed: true. Opaque MCP output cannot provide that proof. Confirmed recoverable command failures can continue without replay; actual Stop and unknown accounting still prevent continuation.

Source admission and checkpoints

sdk.skills.find and sdk.skills.read are discovery/diagnostic previews. inspect(sessionId, skillId, expectedDigest) returns complete supported source, dependency/provenance inventory and an exact review digest. Only an actual-user admit command can retain scoped, expiring publisher evidence and restrictions:

const { inspection } = await sdk.skills.inspect(sessionId, skill.id, skill.digest);
const grant = await sdk.skills.admit({
  sessionId, skillId: skill.id, expectedDigest: skill.digest,
  expectedInspectionDigest: inspection.digest,
  publisher: { kind: "unverified-local", acknowledge: "publisher-not-verified" },
  access: "read-only", paths: ["."], validHours: 24,
});
const source = await sdk.skills.consume(sessionId, skill.id, skill.digest);
// source.body is complete untrusted guidance, not permission.
await sdk.skills.revoke(sessionId, grant.id!, 0, "Reviewed source revocation");

sdk.capabilities.delete(capabilityId, expectedRevision, true) removes one standalone imported skill from its project's registry after an exact revision check. Plugin-owned skills (capability_plugin_owned) and other capability kinds (capability_delete_kind) are refused. Admissions of a deleted skill fail closed on their next check; earlier versions remain in the encrypted event history.

Use the unverified option only after reviewing a Local/registry publisher acknowledgement. Archives require publisher.kind: "pinned-ed25519", an explicit identity label, public key and signature of skillSignaturePayload(origin). The signature covers exact version/artifact/file hashes, not an external PKI or automatic trust in the identity label. Protocol 112 adds sdk.skills.savePublisher(identity, publicKeyPem) (returns the SPKI SHA-256 fingerprint as id) and publisher: { kind: "saved-ed25519", fingerprint, signature }, plus sdk.skills.block("key" | "artifact", sha256, reason) for permanent per-profile blocks; the snapshot exposes skillPublishers and skillTrustBlocks. inspection.scan carries the deterministic SourceIndicatorReport (also exported as scanSourceIndicators for previews), and scriptReviews.read returns indicators. Findings are advice, never grants. audit(sessionId) returns original admissions and monotonic revocations. use inserts the complete selected source into an exact current draft; it fails rather than truncating an oversized draft. consume records model delivery and is also used by the outward MCP gateway. Every later model/tool admission rechecks source authority. Inherited context retains its original source owner and can only narrow the consumer's current permissions at the same actual Local root.

sdk.checkpoints.list(sessionId) returns real checkpoints, abandoned/current capture metadata, retained rewinds and an honest count of uncaptured historical turns. read exposes the before/terminal manifests and informational state. settle explicitly stops owned work. preview requires one exact target and "conversation" or "workspace"; it reports exclusions, blockers, conflicts and preserved state. After actual-user review:

const { preview } = await sdk.checkpoints.preview(sessionId, checkpointId, "workspace");
await sdk.checkpoints.apply(sessionId, checkpointId, "workspace", preview.digest, [
  { root: preview.files[0]!.root, path: preview.files[0]!.path, choice: "keep-current" },
]);

Supply a decision for every conflict, never infer user confirmation from a model verdict. Fresh root/profile/store/peer, policy, context, bytes and revision checks run at effect time. Local, pinned Remote and private Sandbox share this API, but retain their distinct execution/backup/publication boundaries. inspect, stop and acknowledge bind the original operation and exact inspection digest; partial work never becomes completed through acknowledgement. prune and pruneCapture revoke only reviewed snapshot compartments, preserving history witnesses, actual filesystem backups, independent artifacts and costs. Restart never fabricates old captures or replays tools/model calls. See CLI/TUI/desktop usage (not public yet).

Protocol 94 added authenticated exact-project GitHub search/read tools and native single-Enter input. The metadata-only upgrade preserves encrypted events, grants, receipts and saved provider source; fresh tool-ID normalization happens before the first new completion, not on replay. The follow-up contract (not public yet) retains original protocol93 qualification and its separate native gates. It preserves protocol93 PR-bound CI watches and protocol92 integrated model/control/candidate paths. Protocol 91 added reviewed URL-list imports and actual-user shared-config remote changes (not public yet), preserving protocol90 naming/live input and protocol89 indexed event reads, responsive startup/lifecycle and counted session navigation (not public yet). The atomic read-index migration preserves genuine 88 ciphertext, keys, grants, receipts, budget holds and saved input. Its root-owned global capacity reuse never caches speculative transactions or treats unknown usage as free. It retains protocol 85 owned SSH/native decisions, metadata finishing and model-free scheduled preparation (not public yet). It preserves protocol84 retained model recovery, scheduled input and evidence-qualified Kupo modes (not public yet), preserving protocol83 content/script safeguards and protocol82 shared workflow commands, ranked methods and direct MCP schemas (not public yet). It retains protocol81 exact session request recovery (not public yet) and built-in reviewed Git (not public yet). It preserves the genuinely combined80 model-continuity, theme, queued-command, project-folder and grouped-Sandbox lineages and their original encrypted history. Its distinct workflow-command and tool-preference migration markers are appended atomically alongside the preserved81 markers; earlier native/package receipts qualify only their original bytes. Existing features include direct effort and exact context-window shortcuts (not public yet), cascading model controls and complete slash discovery (not public yet), per-question refreshed side context (not public yet), saved turn, cache and live usage telemetry (not public yet), session reliability, streaming dictation and shared controls (not public yet), automatic Kupo and its shared capability inventory (not public yet), project Kanban continuation and provider-equivalent prices (not public yet), remembered approvals and repository-aware GitHub workflows (not public yet), skill gateway and graphic workspace dashboards (not public yet), lean tools and coordinated sessions (not public yet), session-owned candidate cleanup (not public yet), shared-global/last-selected model defaults and ephemeral browser control (not public yet). Schema 57 rekeys only exactly recorded generation output and retains required accounting; the earlier schema-55 model-default upgrade is metadata-only. Schema 58 strictly converges the candidate-retention and earlier development lean-tooling lineages using their actual markers, preserving both guarantees. Older running services require reviewed restart. ToolPreferencesSchema, toolMethods, defaultToolPreferences and effectiveToolPreferences are browser-safe exports. Set the complete four-ID settings.values.toolPreferences.order with an exact settings revision, or reset the toolPreferences section. Ranking is model advice, not permission. sdk.workflows.start(sessionId, kind, prompt?, expectedDraftRevision?) shares the new presets; sdk.sessions.spawnPrompt(sessionId, prompt, expectedDraftRevision?) atomically assigns an actual Manual child. /continue takes no prompt. Direct MCP aliases are model-facing discoveries, not user-supplied permission metadata or a new credential API.

Unified My Work

sdk.myWork owns one explicit cross-repository attention workflow. Sources start empty; discovery/configuration selects one actual Local project/workspace root, upstream and numeric controller gh account. It never scans other repositories, switches credentials, inherits an SSH account or starts a scheduler/model.

const { preview } = await sdk.myWork.previewSource({
  env: "Local", projectId: "explicit-project",
});
// Display the exact account/root/upstream review and get actual user consent.
const source = await sdk.myWork.configure(preview, true);
const admitted = await sdk.myWork.refresh([source.id!]);
const { refresh } = await sdk.myWork.wait(admitted.id!);
const inbox = await sdk.myWork.query({ category: "pending-review", state: "open" });
// refresh.status describes the read, never CI success or merge clearance.

query(filters,{offset?,limit?,signal?}) reads retained observations only. Filters include exact itemId, category (open-pr, pending-review, failed-ci, unresolved-thread), repository, numeric account ID, project/source ID, PR state, freshness and text. Canonical item IDs are stable across category/head/state changes. Each MyWorkEntry retains separate account/root associations, exact related session IDs, original/current-head CI watches and prior complete evidence. Incompatible heads are not combined; missing/failed sources remain visible even when no item matches the selected filter.

status() returns original sources/refresh ownership. read(id,{sourceId?, metadataOnly?,signal?}) inspects immutable original observations without resolving a replacement root. wait uses metadata-only reads and never retries dispatch. Responses are bounded to 8 MiB; select an original source or refine page size/ filters instead of accepting a truncated response. A refresh covers at most 100 configured sources, 1,000 tracked PRs per source, 1,000 requests/threads per PR and the existing count-checked CI bounds. Complete within five minutes means an observed collection, not atomic provider state or continuously watched CI.

refresh(sourceIds?,{timeoutMs?,commandId?}) admits one retained read job. Identical concurrent requests reuse its original identity; competing sets fail. cancel(id) stops only that inbox reader, never a retained CI watch or GitHub job. Stopped/failed/partial reports preserve earlier observations. Unconfirmed cleanup blocks overlapping reads until inspect(id,revision,originalInputDigest,true) records actual user inspection. The original remains partial/unconfirmed; inspection is not cleanup proof, permission or replay. Missing receipts cannot authorize another reader. toggle(sourceId,revision,enabled) changes only explicit source configuration. Changed root/upstream/policy/account needs a new review.

navigate(itemId,sourceId) returns exact retained session associations, without provider reads or writes. previewFollowup(itemId,sourceId) separately rereads that exact source, and start(preview,sourceId,true) reuses session.from-work to create one idle session with an unsent draft and ordinary project controls. It does not check out a branch, send a prompt or approve tools. markRead(itemId) only acknowledges existing attention. User/team/bot/mannequin/enterprise-team review requests and unresolved/outdated threads come from actual provider state; team membership and model answers are never inferred.

CLI: moguri my-work query --filters JSON, source PROJECT_ID, configure PROJECT_ID --digest SHA --confirm-review, status, refresh [SOURCE_IDS], read REFRESH [SOURCE], wait REFRESH, stop REFRESH, navigate ITEM SOURCE, followup ITEM SOURCE, start ITEM SOURCE --digest SHA --confirm-review, and inspect REFRESH --revision N --digest INPUT_SHA --confirm-review. TUI's My Work tab and /my-work share these APIs; slash commands stay ordered user commands, not model prompts. Desktop's Dashboard / My work keeps the active-session dashboard and adds the inbox, filters, original reports, read acknowledgement and explicit scoped follow-up.

Repository import and remote relocation

projects.imports.preview({text,parent}) accepts up to 100 URL/bullet lines and returns a RepositoryImportPreview with every normalized source, canonical destination and clone/register/duplicate/conflict decision. Preview does not clone or authenticate. Submit the unchanged review with projects.imports.start(preview,true,commandId?); retain that canonical command ID if its acknowledgement is lost. The result ID names a profile-owned batch, not a completed import.

projects.imports.list() reads the shared snapshot; read(batchId) returns the original encrypted review and live per-item results. wait(batchId,{signal?,timeoutMs?}) waits for the existing job, never retries it; cancel(batchId) cancels only that original owner. Earlier successes and partial directories survive. A partial batch is not whole-batch success. Unknown effects retain their writer boundary even when a destination is missing. Only after actual inspection may acknowledge(batchId,line,expectedRevision,true,commandId?) release that exact terminal partial item's hold. It neither asserts cleanup nor starts another clone.

const { preview } = await sdk.projects.imports.preview({
  text: "- https://github.com/generated-owner/one\n- git@github.com:generated-org/two.git",
  parent: "/absolute/existing/parent",
});
// Present all entries and obtain actual user review before this call.
const started = await sdk.projects.imports.start(preview, true);
const { batch } = await sdk.projects.imports.wait(started.id!);
if (batch.status !== "completed") {
  console.error(batch.status, batch.items);
}

projects.remotePreview(projectId,remote,url,workspaceId?) explicitly reviews a Local checkout and every linked worktree sharing its common config. projects.setRemote(preview,exactConfirmations,true,commandId?) reuses the independently retained Git operation API; read/wait/cancel/acknowledge through sdk.github. It atomically changes only the reviewed remote URL fields without fetch/push/authentication or changes to branches, index and working bytes. The review includes Git's actual expanded fetch/push URLs for each worktree; safe same-repository HTTPS-to-SSH rewrites do not become an undocumented fallback. Current metadata/reviews and scoped remembered Local Git/command approvals are invalidated; immutable PR/candidate sources and accounting remain unchanged.

git.remote.set is an actual-user action in GithubActionSchema, deliberately excluded from model-facing GitActionSchema/git_write. Remote/Sandbox sessions cannot borrow a Local scope. Browser and React exports contain these typed APIs, not Node filesystem/process code. Protocol91's paired import/remote markers preserve original 88/89/90 ciphertext, receipts, grants and unknown holds.

Recovery, scheduled input and Kupo

These methods use the same authenticated immutable-profile SDK and existing /v1/commands, snapshot and event authority. A command result identifies retained intent/admission, not successful model work. Preserve an uncertain command ID and inspect its original receipt rather than sending a replacement.

Surface Contract
sessions.retry(sessionId, failureId?, revision?) Retry the original last eligible model failure; preserve draft/context/queue and earlier effects. Read Snapshot.modelFailures and modelRecoveryCycle for actual state.
scheduledPrompts.create(sessionId, timing, draftRevision?) Capture and consume only the exact saved draft/attachments/controls into a durable unsent record.
scheduledPrompts.list(sessionId?) Read this profile's original scheduled records. scheduled/blocked stay outside model history; queued is claimed but not a sent prompt until admitted.
scheduledPrompts.sendNow(id, revision?) / cancel(id, revision?) Share one-at-most timer ownership; cancel only undispatched original input, not an unrelated turn.
routing.modes(sessionId) Read mode readiness and genuine unmet gates. No classification or model call.
routing.options(sessionId, proposedOptions?) Review exact shared working-window/thinking eligibility for automatic, explicit Single or reviewed Compound Kupo in the owning Env. Compound includes its classifier and every eligible route role's real output bound. Returns eligible model IDs, genuine common presets/efforts and an explicit unavailable reason, without changing controls or calling a model.
sessions.kupoMode(sessionId, mode, revision?) Explicitly select balanced, savings or performance for automatic Kupo without changing autonomy/Env.
routing.profileDraft(input) Prepare an unpersisted source-review assertion; explicitly save its exact profile in the full Kupo policy after reviewing it.
tools.history(sessionId, input?) Page retained original public prompt/model/tool/answer sources, including after compaction; no private roles, console data, hidden thinking, drafts or queued input.

Interrupted chats (protocol 115)

Surface Contract
sessions.interrupted() Chats with a recorded Session.interruption (cause, turnId, queuedItemIds, at) that are not archived.
sessions.continueInterrupted(sessionId) Release the recorded waiting prompts and, when a turn was running, queue the continue workflow ahead of them. Rechecks policy, Env and model.
sessions.continueAllInterrupted() Continue each interrupted chat; returns { sessionId, error } per chat so one failure doesn't stop the rest.
sessions.dismissInterruption(sessionId) Forget the record without continuing; held prompts stay held.

settings.interactions.continueInterrupted (ask or always) controls whether the service continues interrupted chats automatically after a restart. executeInterruptedCommand is the shared /interrupted helper. See the contract (not public yet).

Automations (protocol 115)

Surface Contract
automations.list(projectId?) / runs(automationId?) Read Snapshot.automations (deleted ones omitted) and recent automationRuns (latest 50 per automation plus every active run).
automations.create(projectId, definition, { enabled, controls? }) Capture full controls from the project defaults plus explicit overrides. enabled is the explicit activation; nothing runs while paused.
automations.update(id, definition, controls?, revision?) Replace name, schedule and steps; overrides apply on top of the captured controls. Active automations re-anchor at the edit.
automations.enable(id) / pause(id) Turn scheduling on from now, or stop future occurrences (an active run continues).
automations.runNow(id) Start one run now in a new chat; refused while a run is active.
automations.stopRun(runId) / delete(id, { stopRunning? }) Stop a run's chat so later steps never run; delete refuses an active run unless stopRunning.

AutomationDefinition is { name, schedule, steps }; parseAutomationWorkflow reads the readable YAML/JSON workflow syntax after parsing, and executeAutomationsCommand is the shared /automations helper. Semantics for DST, missed and overlapping occurrences, script steps and restart are in the automations contract (not public yet).

ScheduledTiming is {kind:"delay",minutes,timeZone} or {kind:"at",at,timeZone,localTime,offsetMinutes}. Use scheduleLocalChoices("2030-10-27T02:30","Europe/Rome") to review both DST occurrences, not guess one. Timings must be future and within one year. Service-owned deadlines survive UI disconnect. Overdue schedules are checked once after restart; no timer runs inside the client.

History defaults to twenty messages and 12,000 UTF-8 bytes per page. Retain the returned throughSequence, messageOffset, limitMessages and digest for byte continuation with nextOffset. Only after that window ends, advance to nextMessageOffset with a new digest. Its boundary is explicitly scoped-controller-public-history in every Env, not authority to read a workstation/remote filesystem. Model access still needs ordinary tool policy.

Common errors include revision_conflict, model_retry_*, schedule_changed, schedule_dst, schedule_terminal, routing_effort, routing_frontier, routing_evaluation, routing_context_bound and budget_*. These retain original input and distinguish changed authorization, unsupported transport, source review, unknown accounting and exhausted capacity. Do not repair/clamp a request, infer zero cost or treat model confidence as permission.

Pooled tuning uses the existing revision-bound sessions.modelOptions(sessionId, options, revision) command. Review with routing.options first, then save an explicit choice. Unsupported pool members are excluded before classification; the exact actual prepared role is checked again before dispatch. A configured classifier is never silently replaced. The model's advertised binding remains unchanged even when its admitted working ceiling is smaller. Kupo routing preference, Env, autonomy and cumulative budget remain distinct. Its classifier and qualified per-model mapping select actual thinking automatically; manual Kupo effort commands return routing_effort without mutation or inference. Old overrides remain retained and blocked until explicitly cleared; context and budgets are not silently changed. Performance still requires its qualified maximum context and xhigh/max. Complete future reviews/revisions and finite holds use the same selected ceiling.

Reviewed Compound additionally binds these options into its immutable policyJson, checks every complete future role/test envelope before admission and rechecks actual options/metadata at dispatch. The source/staging/test review remains mandatory; ordinary chat does not start a compound implicitly.

The desktop model menu exposes Kupo Routing and Context window, with automatic thinking, and no role-effort override. routing.options.thinkingLevels remains an empty compatibility field, not user-selectable pooled thinking. SDK, CLI and actual TUI share /thinking, /effort, /context-window and /model-settings; none sends a model prompt. Thinking levels apply only to fixed models. Default clears only the selected override, and rejected/stale changes preserve the draft, history and original controls.

const sdk = await connectMoguri({ autoStart: false });
const session = sdk.getState().snapshot!.sessions[0]!;
const scheduled = await sdk.scheduledPrompts.create(session.id, {
  kind: "delay", minutes: 10,
  timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
}, session.draft.revision);
const prompt = sdk.scheduledPrompts.list(session.id).find(p => p.id === scheduled.id)!;
await sdk.scheduledPrompts.sendNow(prompt.id, prompt.revision);

Creation above requires a nonempty saved ordinary draft; it never writes replacement text or grants permissions. Native TUI and hidden desktop consume these same APIs. The independent packed consumer exercises actual installed worker retry, scheduling, mode readiness, history and restart alongside browser/React/Node imports/types and its own dependency audit.

Schema 59 adds an independent transactional metadata marker. Older source settings normalize to no configured skill sources; ciphertext, receipts, identities and existing accounting are unchanged. Schema 60 retains reviewed child-session detachment and schema 61 adds session approval/GitHub metadata without rewriting encrypted history. The exact private approval-development schema-59 lineage also converges by its own retained marker, atomically adding the workspace/navigation markers. Missing or ambiguous provenance is rejected rather than guessed. Schema 64 adds card ordering, per-request continuation choices and captured read-only GitHub board sources. issues.reorder binds the complete source and destination structure; kanban.choose binds the actual profile and exact saved draft revision. /continue-work returns a typed route review before dispatch. BoardConfig.githubSync controls optional issue import and explicit column mapping, while IssueBoard.githubSource is service-owned provenance, never client-supplied authority. Older encrypted history and consent remain intact. Schema 66 adds the transactional retained_telemetry_schema marker and requires Snapshot.sessionTelemetry. Original events, encrypted grants and receipts are preserved. Exact original provider results may append same-call cache-category corrections using only the captured rate; unknown work and holds are not refunded. Schema 63 explicitly converges the independent automatic-Kupo schema 61 and session/GitHub schema 61, plus Kanban/pricing schema 62. Exact original markers, approvals, selected responses, encrypted history, receipts and held accounting survive failure and reopen; a missing current marker is never silently repaired. It retains protocol-54 exact-scoped session PR observations and shared session-status indicators (not public yet), and combining the separate Agent terminal (not public yet), chat activity and compact usage (not public yet), desktop interactions (not public yet), protocol-52 managed Sandbox (not public yet), protocol-51 session interactions (not public yet), and the protocol-44 through 50 settings/native lifecycle slices. It retains protocol-43 document attachments (not public yet), including protocol-42 task completion estimates (not public yet), extending the protocol-41 owner-requested platform workflow extension (not public yet). The prior issue-17 source used protocol 40 for shared model windows/scoped paste, native execution, reviewed Local compound workflows, finite Local wind-down and owned bounded decisions. It does not replace the immutable qualified archives listed below. See native source qualification (not public yet) for the actual generated VM evidence and remaining client/environment gates.

sdk.browser.state(sessionId) reports the actual desktop-owned pane and its current control identity. The user enables/disables access with the pane's Agent control switch. mcp.tools with serverId: "builtin" and query "navigate" discovers browser_navigate; query "browser" discovers all six tools, including browser_status and browser_snapshot. Invoke through the existing mcp.call/mcp_gateway policy/approval flow, supplying its discovered schema digest and fresh control/element identities. Reads/interactions also copy the exact expectedUrl from status/snapshot. Protocol 73 carries the service-admitted website scope to the actual host, including redirects, subresources and WebSockets; clients cannot invent a substitute grant. Results keep the normal encrypted session/job retention and bounded result.read paging. Native input acknowledgement is not verification of a website's business action.

The browser-safe sdk.browser.host methods attach, poll, reply, detach and monotonically change control for an explicitly authenticated native host. Its private lease belongs only to that original profile/session/view; never put it in model context or configuration. Browser availability and control are ephemeral and are not restored by command-receipt replay or service restart. CLI/TUI agents use the same builtin tools when the actual desktop pane is open and enabled; without it they report unavailable rather than launch a browser. Only Local is qualified for this capability.

sessions.progress(sessionId) reads the explicit current model plan when present, otherwise the separately bound workspace-file checklist, and compares it with optional owning-model advice. useTaskProgress in moguri/react refreshes every 15 seconds without overlapping polls or model calls. CLI moguri progress --session ID and /progress expose the same typed observation. Unknown, stale and disagreeing estimates never change actual lifecycle outcomes.

sessionIndicator(session, snapshot) is a browser-safe selector for actual work/input/completion and separately verified linked-PR state. It includes labels, prState and prLabel; optional heuristic questions are explicitly not structured answer requests. sessionPullRequestUrl, sessionPrScope and sessionPullRequest resolve the same direct, work-item or exact managed-change source in SDK/desktop/TUI commands. Reading these selectors performs no network, filesystem, model or Git action.

sessionBackgroundWork(session, snapshot, activity) is a browser-safe selector for background display. agentSessions retains inspectable nonarchived original subagents/coordinated children; agents contains only their active turns. commands, jobs and count combine current running command/script activity with actual command/watch jobs, deduplicating by owning turn and call ID. Visual nesting, pending approval, finished/archived work and another session's activity do not count as running. complete is false for missing/foreign/bounded activity; callers must disclose a lower bound rather than invent an exact zero. It reads only supplied observations and grants no child control or PID authority.

sessionNavigationStatus(session, snapshot) uses the same canonical indicators for Finished/Error/Needs attention/In progress filtering. Idle, held and stopped states are not relabeled successful or active. compareSessionPrompts(a, b, "newest" | "oldest") compares each session's latest acknowledged user message, falling back to its real creation time only when unsent. These are pure view selectors: they do not rewrite stored order, group/pin ownership or lifecycle.

sessionLocalFolder(session, snapshot) returns { path, identity } for the session's actual Local root (ready managed worktree with its recorded device/inode, project checkout, or a project-free chat's captured Home), or { diagnostic } for Remote/Sandbox Env, several captured repositories and unready, removed or foreign worktrees. It never falls back to the base checkout. It is a pure view selector; clients that open the folder must re-verify the canonical directory and identity before delivery.

workspaceDiffSummary(diff) returns additions, deletions and binaryFiles from a complete ordinary unified diff, validating text-hunk lengths and treating binary changes separately. Unsupported/incomplete input throws workspace_diff, never a partial-looking successful total. Apply it only to the actual bound-root workspaces.git response; its HEAD-relative, protected-path-filtered tracked scope is not an untracked-file or whole-PR summary.

Session.prObservation is optional for older history. A new session.pr_observed event retains profile/session/URL/project/workspace/root/revision, access mode and configuration revision with actual GitHub state/draft/checked time or diagnostic. It does not increment the session revision, activity time, unread state or lifecycle. Metadata is not a user answer, PR-write permission or evidence that the session's work succeeded. Legacy missing draft remains unknown; project-free scope cannot inherit a root or authenticated account. The schema-54 marker upgrades transactionally without rewriting ciphertext.

Execution-machine model readiness

models.readinessTarget(sessionId, modelId, signal?) resolves an exact configured model's profile/session/Env/root/peer/build binding. models.readiness(sessionId, modelId, mode?, signal?) returns bounded observations and explicit source, unknown and requirement checks. Informational is the default; required rejects missing/incompatible/unknown required runtime/model evidence. Neither method selects/enables a model, starts a server/guest, downloads weights or calls inference. Network/proxied endpoints cannot borrow execution-host hardware as server-capacity proof.

configuredReadinessModels(catalogue, env) includes explicit unavailable or unselected configured endpoint models for inspection, not inference admission. Configuration uses optional endpoint runtime and model requirements fields. The complete provenance, bounds and actual-Env restrictions are in the runtime-readiness contract (not public yet).

models.runtimePreview(sessionId, modelId, signal?) returns an exact llama.cpp version-command review; observed immutability is still required at dispatch. Only after actual-user confirmation call models.reviewRuntime(sessionId, modelId, expectedDigest), then models.readinessWithRuntimeReview(sessionId, modelId, reviewId, mode?, signal?). The original review is consumed before I/O and cannot replay after failure, cancellation or restart. The generic delegated platform cannot issue or consume that review; neither a literal actor field nor model/autonomy advice approves it. Ordinary refresh never reuses it. Report freshness remains ephemeral and does not become a model-availability, quality or permission decision.

Captured folder sessions, side chats and streamed speech

projects.group(name, [{ projectId, revision }, ...]) atomically creates a named navigation folder and moves the exact reviewed projects into it, without moving files. sessions.createFolder(folderId, title?, overrides?) captures the current member IDs/revisions and canonical path/device/inode identities. Its Session.projectId is null, with immutable paired projectFolderId and repositories. Null without those explicit fields remains project-free; ordinary Local chats may separately retain homeRoot, never a synthetic project.

Local and qualified managed Sandbox filesystem/command tools require an explicit repository ID or captured name for folder sessions. workspaces.files(sessionId, path, repository), file(sessionId, path, repository) and git(sessionId, diff, repository) resolve the same bound root; terminal.open requires a captured member's exact root. Replaced directories, unknown/ambiguous selectors and unqualified transports fail without selecting a first member, common parent or HOME. All captured roots participate in writer admission, cancellation and uncertain-work quarantine, including across profiles. Per-member folder restrictions and project-scoped approval grants bind the actual selected repository.

CLI/TUI/desktop share /folder-group {"name":"Folder","projectIds":["ID","ID"]} and /folder-chat [FOLDER_ID] [Local|Sandbox]; without an argument it lists visible folders. Env defaults to Local; explicit Sandbox requires a ready reviewed native runtime and managed automatic workspaces. Hard allowed-env policy still applies, with no fallback. Each member gets a private copy and tools keep explicit selection; any member's folder restrictions block all group shells. Per-project GitHub/plan, MCP, memory, hooks, background and managed-worktree surfaces are not implicitly combined. Group source publication separately chooses one original member; native user consoles and SSH groups remain unqualified.

sessions.side(parentId) atomically opens the original side conversation or creates one with inherited controls and captured full parent context. It never runs inference or grants write/coordination authority. The root set is inherited unchanged for folder sides. Navigation nesting alone does not grant context. Before each new side turn, the service refreshes from its actual createdParentSessionId, atomically retaining turn.started.sideContext and child-owned source grants. Session.sideContext exposes the original source watermark/digest and owning turn/time; it is retained provenance, not model authority. Later main work appears in the next side question, while earlier side exchanges and in-progress continuations keep their exact previous inputs. Fresh inherited images/documents require actual selected-model support and full input/window/budget admission. Private roles, unsent drafts and held main queues are excluded; no paid retry, truncation or alternate parent is used. The same behavior applies to SDK, TUI and desktop callers. Protocol/schema 67 adds its atomic metadata marker without rewriting legacy captures or receipts.

sessions.askSide(parentId, prompt, expectedDraftRevision?) atomically reuses or creates that read-only side and enqueues the original question without replacing its saved draft. When a main /side ... draft is consumed, the exact revision, prompt and attachments are bound in the same transaction. Retained queue command origin prevents a lost receipt from replaying admitted work. The slash result opens the side panel; ordinary model/budget/Env/permission gates still apply.

commands.list(sessionId, signal?) returns complete SlashSuggestion values, built-ins before fresh enabled gateway skills, paging one exact catalog digest. skills.use(sessionId, id, digest, expectedDraftRevision, replacementText?) loads only the exact fresh source and retains actual-user skill.loaded provenance and encrypted grants. It is guidance, never a tool permission or paid call. The loaded body becomes a skill attachment on the draft (text = replacementText or the current draft, never the body); sending the draft delivers the body to the model as <user-selected-skill> context while chat shows the prompt and a skill chip. User-selected loads add no separate activity row. Installed and configured skills share the same bounded selection path. Model/native and outward MCP consumption use the same explicit successful-load event, bound to the exact source and native call when present. Discovery and diagnostic reads never emit it. Historical skill.used records stay inspectable.

Desktop dictation uses voice.startCapture(sessionId, id?, { streaming: true }), ordered appendCapture(..., sequence, pcmBytes), volatile readCapture(...): { text, revision }, then finishCapture(..., finalSequence). The microphone button toggles record/confirm on separate clicks. The factory Ctrl+Space shortcut is held press/release. voice.shortcutMode:"toggle" is an explicit independent shortcut choice; "hold" or an absent mode keeps PTT. The obsolete voice.pushToTalk button preference is retained unchanged and never determines shortcut mode. Protocol 88 migrates existing stores without inventing a user choice. Renderer gesture ownership prevents an old shortcut release from finishing a newer click-owned capture. Finish acknowledges flush intent; await the original job separately for the exact completed transcript. Frames are mono 16-kHz PCM16, bounded per frame and capture, authenticated with the transient original nonce, never journaled. DraftEditor.startDictation guards the provisional insertion span against concurrent/foreign edits. Batch WAV upload and reviewed transcript insertion remain separate APIs. Reconnect/restart cannot replay PCM, and cancelling a retained partial job never acknowledges uncertain cleanup as successful.

voice.enable(true, expectedSettingsRevision?) reviews the pinned license, enables voice and downloads its sole managed model through an owned job. voice.disable(true, expectedSettingsRevision?) joins this profile's voice work, closes its recognizer and removes only the exact managed model/staging. voice.prepare() warms the qualified recognizer without microphone access. voice.inspectModel(absolutePath) starts a read-only voice.inspect job that reads the header, confirms streaming support and hashes the file; voice.inspection(jobId) returns its VoiceModelInspection. voice.trustModel(jobId, expectedSettingsRevision?) locks that exact reviewed path, size and SHA-256 as settings.voice.model and enables dictation; it fails with speech_model_changed if the file changed after review. voice.useManagedModel(expectedSettingsRevision?) clears the selection without touching the file. settings.update cannot select or alter voice.model (speech_model_review). voice.status() reports model.source, runtime and trust (trusted, unverified, changed with observedSha256, missing); a changed digest blocks preparation and capture with speech_model_changed. voice.enabled defaults true for the dictation feature; explicitly saved disabled choices remain disabled. This neither opens a microphone nor downloads weights. Runtime/model preparation checks configured readiness first rather than creating failed jobs on unconfigured chats. voice.standby is separate user consent for the focused desktop composer's visible, scoped microphone standby. External model directories are never deletion authority. The standby-ready state is a scoped microphone icon/accessible description, not a repeated paragraph in every chat. An acquired capture recorder exposes its readiness acknowledgement separately from physical ownership: release can flush already captured PCM while that acknowledgement is pending. Release before hardware acquisition still cannot start a late microphone or invent spoken audio. Streaming partial/final text stays in the exact owning draft; buffers are wiped, and any batch WAV spool is removed after its owned use.

Session IDs, dependencies and interactive outputs

sessions.get(id).id and /session-id expose the real stable identity; /session-id also reports its git-style short ID (sessionShortId(id), the first eight hex digits). resolveSessionReference(sessions, reference) accepts a full ID or a :short prefix of at least eight hex digits and returns every match: more than one is ambiguous and clients attach nothing. Desktop shows the short ID in Insights and offers Copy session ID in the session context menu; the chat header shows only the title. The TUI header shows the short ID. A typed :short mention and /attach-session SHORT_ID resolve through the same reviewed attachment flow. Service log lines for failed requests name the request type and short session ID. attachments.sessionPreview(destinationId, sourceId) and attachments.session(destinationId, sourceId, digest, true) retain reviewed public context, including archived sources. ID matching never grants execution or private transcript/console access.

sessions.waitPreview(sourceId, targetId) captures one current target turn or already queued task. sessions.waitFor(preview, true) saves that exact success-only dependency; sessions.cancelWait(sourceId, waitId, revision) removes only the observed wait. Stop cancels a user's wait and holds undispatched input. Failure, stop, deletion, archive, changed scope or unknown completion never releases it. /wait-session uses the normal command queue; unheld /stop stays the existing live escape hatch.

sessions.bulkPreview({action, sessionIds, targetSessionId?, children?}) and sessions.bulk(preview, true) atomically apply reviewed same-project homogeneous attach/detach or settled whole-set archive/delete. children is cascade or detach for unselected descendants. sessions.prStatus(sessionId, url) (protocol 112) reads one linked PR's reviews, merge state, head checks and the Local checkout branch without retaining anything; prStatus, prActionPrompt and PR_ACTION_LABELS are browser-safe, and workflows.start accepts the address-review, fix-conflicts and fix-ci presets. Profile-scoped retention.confirmBulkArchive/confirmBulkDelete skip only UI confirmation, never the running-session warning (confirmRunning). coordination.preview/grant enable explicit same-profile public peer messages, not parent-style dispatch/stop permission. sessions.associatePr(id, source) requires the exact verified github.source plus expectedDigest; selecting an additional PR never changes first-association cleanup provenance.

Built-ins goto_definition and find_references use the pinned TypeScript 7 native semantic API over an approved JS/TS corpus: 200 files, 128 KiB each, 2 MiB total, 1-based UTF-16 positions. Returned snapshotDigest binds the root, complete query and exact source set for continuation. Standard libraries, installed dependency types, custom config/plugins and other languages are not silently replaced by regex results. find_in_array, order_asc, order_desc, find_bigger and find_smaller accept bounded typed values with stable, non-coercing comparisons. Discover schemas through tools.catalog.

chatOutputs.renderHtml(sessionId, title, html) and render_html deliver exact retained HTML up to 128 KiB. Desktop opens an isolated interactive document, without Node, Moguri access, network, file input or navigation. CLI/TUI expose the original source and a truthful non-rendering boundary.

click, type, wait and take_screenshot use the exact user-enabled Local Browser pane, controlId, expected URL and fresh element refs. The matching MCP primitives remain available. apps.run(sessionId, {launch, actions}) is a bounded playwright batch for a newly owned Electron or headless Chromium instance, never a personal app/browser. Launch selects an exact installed regular executable and relative Electron entry or approved website URL. Chromium denies out-of-scope HTTP/WebSocket traffic, service workers, WebTransport, WebRTC and new workers. Password/file/hidden inputs are refused. Normal Local host execution is not SendBox containment; non-Local and restricted-folder/read-only app launches stay blocked. No browser is downloaded automatically. Known target closure does not prove detached-descendant cleanup.

Screenshot bytes are normalized and retained as typed chat attachments under their original user/model tool actor, not implicitly added to provider image context. attachments.read(sessionId, attachmentId) retrieves their genuine bytes. Partial/cancelled/lost work is not replayed or called successful. github.browse resources files and jobs bind exact PR/run IDs and head SHA; the PR pane's Files/Actions/Reviews and reviewed watch use the same account/root and expose stale/unavailable data without acquiring GitHub write authority. Protocol 116 adds bounded resources tags, release-latest, release-tag {tag}, annotations {checkRunId, headSha}, contents {path, ref?}, settings, rulesets and branch-rules {branch}, and the reviewed github.repo.settings action. GithubModelActionSchema/isGithubModelAction name the subset the github_write agent tool may preview and execute.

capabilities.propose(projectId | null, kind, name, content) accepts null (protocol 116) for skills and scripts that apply to every chat; scriptEntries(registry, projectId) returns the scripts a chat in that scope sees, with project scripts shadowing every-chat scripts of the same name.

Retained PR CI lifecycle

Protocol93 adds github.ci(scope, pullSource, signal?, expectedBinding?) for a freshly verified PR source plus its independently retained watch history. currentWatchId is only a head/source association, not proof of green CI. The browser-safe githubCiOperationMatches helper uses actual profile, project/workspace, canonical root device/inode, numeric account, repository and PR number; it never attaches an older head-only watch by SHA.

github.previewCi(scope, pullSource, {headSha?, timeoutMs?, pollMs?, signal?, binding?}) previews a PR-bound github.ci.watch with prNumber and accountId. The pair is required together; legacy head-only actions retain their original meaning. Changed account/root/head invalidates review. ciForSession(sessionId, prNumber?) and previewCiForSession(sessionId, prNumber?) share selection with CLI/TUI, using a unique linked PR only when no number is supplied.

After actual-user review, github.execute retains original admission before dispatch. Concurrent starts for that exact source return its original watch, not another poller or a transferred owner. Missing original receipts do not authorize another start. github.read(watchId, signal?) works independently of source retention and adds ciObservation: the original normalized, credential-redacted complete collection, source target, time and state. Its encrypted grant belongs to the operation, not the source session.

The operation's optional ci metadata holds its immutable target, observation digest, latest actual observation time, state/count, completeness/deadline and unconfirmed-cleanup fact. All declared check/status/run pages must agree before publication. Failure annotations are separately verified against their original check/head. There is no prefix-as-green, unreported account fallback or model call. New granular states do not reinterpret historical legacy results.

Stop and controller-loss recovery preserve partial/unconfirmed evidence without replay. A new independent watch after lost ownership has a separate original intent and actual-user inspection confirmation. CI attention uses the existing event stream with reason ci and the real terminal operation revision, never a solver completion, answer or approval. See the complete contract (not public yet) and usage (not public yet).

Remembered approvals and GitHub entry points

Native file/data/readback operations are factory-policy approved rather than fake human decisions. Stricter explicit review/deny rules still win. Scripts and external MCPs require normal approval/delegation. Explicit Autopilot/Max remains automatic; this policy does not bypass hard environment or budget gates.

webAllowlist.list(sessionId?) returns effective Local entries for that exact session or all entries in the connected profile. add(site, scope, expectedSettingsRevision?) and remove(id, expectedSettingsRevision?) use the existing atomic settings revision and validate original profile-owned sources:

await sdk.webAllowlist.add("docs.example.com", {
  kind: "session", sessionId: session.id,
});
await sdk.webAllowlist.add("https://example.com:8443", { kind: "global" });
const effective = sdk.webAllowlist.list(session.id);
await sdk.webAllowlist.remove(effective[0]!.id);

Project scope is { kind: "project", projectId }; global means this profile, not shared cross-profile policy. Exact hostnames permit default-port HTTPS; exact origins preserve scheme/port. Rules do not confine approved Local shell scripts, broaden Sandbox's actual firewall, authorize Remote, or enable browser control. Model tools cannot apply these settings. /firewall exposes the same user-only API in CLI/TUI and desktop.

Protocol/schema 73 adds an optional permissions.webAllowlist with a strict atomic migration marker. No older record gains grants or changes ciphertext, receipts or accounting. Ordinary read_file refreshes a stale optional digest with explicit sourceVersion provenance and a fresh sourceRef; stale byte continuations restart at zero. requireExactVersion: true retains intentional pinning. Exact write/edit CAS and immutable original tool results are unchanged.

approvals.respond(sessionId, approvalId, allow, remember?) atomically records the actual pending answer and optional { scope: "session" | "project" | "global", match: "exact" | "family" | "tool" } grant. Global means all projects in this profile, not another profile or execution environment. approvals.list() and approvals.revoke(id, expectedSettingsRevision?) share settings revisions. Family grants accept only conservative simple commands; MCP grants bind the actual server configuration and schema. Callers cannot replace the pending command or supply a different grant target. Explicit tool matching permits new arguments to that same named tool only inside the chosen scope and environment. Execution requires an exact command or conservative family rather than a blanket execution-tool grant. /approve project tool uses the actual selected folder member, and approvalProject(session, call.arguments.repository) exposes that same unambiguous project identity for client choice controls.

sessions.autonomy(id, "Autopilot") explicitly sets controls.automaticApprovals: true; Max does the same while requiring its qualified decision provider. automaticApprovalsEnabled(controls) is the shared check: Autopilot/Max approve automatically unless automaticApprovals is explicitly false (the bounded opt-out). Unmarked legacy sessions and saved global/profile/project Autopilot defaults count as automatic; new sessions resolve the marker to true. Original events are not rewritten. Manual/Guided never gain automatic approval through an inherited marker.

await sdk.approvals.respond(session.id, approval.id, true, {
  scope: "project", match: "family",
});
const repositories = await sdk.github.repositories();
const next = repositories.nextPage && await sdk.github.repositories({
  account: repositories.account, accountId: repositories.accountId,
  page: repositories.nextPage,
});
const scope = { env: "Local" as const, projectId: session.projectId!, sessionId: session.id };
const project = await sdk.github.project(scope);
const abort = new AbortController();
const matches = await sdk.github.search(scope, project.repository, project.account,
  "is:issue is:open (UI OR UX OR redesign OR polish)", 1, 30, abort.signal);
const source = {
  kind: "issue" as const, repository: project.repository,
  account: project.account, accountId: project.accountId, number: 7,
};
const reviewed = await sdk.github.source(scope, source);
// Display reviewed.item in full and obtain the user's explicit start action.
const created = await sdk.github.startSession(scope, source, reviewed.digest);

github.repositories({ source: "public", query }) explicitly searches public repositories. Public visibility is not an open-source license claim. Discovery uses only the current controller GitHub CLI account. No Copilot login, secret-backend updater token, rootless filesystem access or SSH fallback is introduced. github.project derives the remote the folder's Git configuration selects, actual default branch, local branch and account; clients do not guess main or an account name.

github.search(scope, repository, account, query, page?, perPage?, signal?) uses typed resource: "search" through github.browse. Terms must not contain repo:, org: or user: replacements or escape the selected repository with unbalanced parentheses/quotes. The complete page must agree with its reported count/next-page receipt, remain inside that repository and fit the 1,000-result search bound. Refine an oversized/incomplete query; missing results are not zero. github.browse also accepts an optional AbortSignal. Cancellation belongs to the original read, never a replacement call.

The discovered model tool github_read accepts {action: "project"} or {action: "browse", input: GithubBrowse}. It pins the actual Local project/worktree's discovered repository, login, numeric account, profile and canonical root; it cannot substitute another repository/account or run in a project-free chat, group, Remote or Sandbox. /github search TERMS uses the same SDK/service read in CLI, actual TUI and desktop. Public fetch_page remains anonymous; no ambient credential forwarding or login API is added.

github.source and startSession bind canonical repository/item identity, numeric account identity, actual profile/root inode and reviewed complete title/body. The returned binding is not a filesystem or permission grant. Session.githubSource retains original provenance; relinking that source clears the current attribution without rewriting history. Session.workItemUrl is the separately typed GitHub issue binding, independent of local workItemId. New sessions contain an unsent draft, not a claimed prompt or changed checkout. Existing github.preview, execute, read, wait and cancellation retain the original exact-review/no-replay write lifecycle.

Lean tools and session coordination

The Node-only globalSkillSources(homeDirectory?) returns disabled Local source presets for .agents/skills and .moguri/skills beneath an explicit home or the current OS user's home. It performs no directory scan or source admission. Review the returned absolute paths, explicitly enable the intended entries, and save through the existing profile-owned settings API before discovery. The desktop confirmation uses these same presets; CLI/TUI consumers can use them without giving the model source-configuration or approval authority. createGlobalSkillFolder(id, homeDirectory?) creates only the exact preset folder for global-agents or global-moguri (desktop calls it on confirmation) and rejects any other id. An enabled Local source whose folder doesn't exist offers no skills instead of failing the combined catalog.

skills.install(projectId | null, skillId, expectedDigest) (protocol 114) re-reads one source skill and installs those exact bytes disabled in a project or, with null, every project. tools.toolsets() returns the built-in tools grouped into toolsets plus the foundational scripts; listing grants nothing. artifacts.library(projectId | null) returns metadata of build outputs and agent-written files with their linked session. suggestions.preview results include tools, repeated requests a script could handle. Contract: skills, tools and artifacts (not public yet).

skills.find(query, { sessionId?, sourceId?, offset?, expectedCatalogDigest?, signal? }) refreshes enabled registered skills and explicit settings.skillSources folders or HTTPS archives. It returns eight bounded metadata entries, source/path, SHA-256, catalogDigest and nextOffset. Supply the catalog digest for later pages: they are served from that first page's metadata snapshot (kept for five minutes per profile, session and source filter), so a listing stays consistent while files change. If that snapshot is gone or the scope changed, the result has restarted: true and begins again at offset 0 of the fresh catalog; restart your listing. skills.read(id, expectedDigest, sessionId?, signal?) always refreshes and returns the whole checked body only when it still matches. Configuration changes, removal, source failure and changed bytes never return a cached substitute body. The optional session binds actual profile/project/Local scope; omitting it is an explicit user control-plane preview, not an inherited project. Configured source discovery on Remote/Sandbox agents remains unqualified.

The moguri/mcp entrypoint adds moguri_find_skills and moguri_read_skill to the existing single stdio gateway. It binds its own session, rejects foreign authority fields and exposes no source-configuration or self-approval tools. SDK/MCP cancellation propagates through the authenticated request into the source download and discards the pending reply. Downloads also have a 15-second deadline and abort on shutdown. No source lookup creates durable capabilities or model calls.

dashboard.overview({ range?, projectId? }) returns all four pages' shared projection: work, days, projects, models, totals and velocity. The default is seven UTC calendar days. Use the existing BudgetRange presets or inclusive custom dates; all-time remains in detailed budget accounting. Unknown dated reports and cost estimates preserve existing provenance. velocity.productivityIncrease remains null: only retained normal agent-turn outcomes, valid timing and actual user approval/answer events are measured. Control/role turns and stopped/partial work cannot become successful tasks.

suggestions.preview(null, true) is a global local-only preview, including deterministic gaps and the actual generation modelId, without session creation. suggestions.generate(null, digest, true, true) creates a settings chat only after exact source/model review and ordinary model admission. Non-null session IDs retain explicit scoped behavior.

tools.catalog(sessionId, query, offset) returns scoped native schemas and digests. Normal model solver turns use the same catalogue through discover_tools, exposing only the loaded native functions at the next boundary. The complete service capability set remains authoritative; schema discovery is not permission. Model-turn-only functions require their actual owner and cannot be called as standalone user jobs.

tools.execute(sessionId, name, arguments, schemaDigest) admits a Local user tool job under exact normal approval, without a model call or Env fallback. Its returned ID is admission, not success: inspect jobs.wait and the original result. tools.results(sessionId, { before?, limit? }) discovers original public sources. tools.resultById(sessionId, operationId, { offset?, expectedDigest?, expectedRevision? }) pages the exact retained source with UTF-8 byte offsets, including after paging, source edits and restart. Pin its digest/revision for continuations. Every public model-tool context includes its actual retainedSource; models need not invent opaque step IDs. The older tools.result(sessionId, stepId, callId, offset) also accepts that call's exact activity operation ID in place of stepId, never a heuristic cross-session lookup. Both preserve outcome/rawComplete; private controls, hooks and other/deleted sessions are excluded. tools.state queries the canonical in-memory todo/memory projection, not persistent internal tables.

sessions.autonomy(sessionId, autonomy, expectedRevision?) is an explicit selection, including reselecting a legacy Autopilot value. It retains actual-user command provenance and automatic-approval consent across later turns/restarts. Loading old values or changing an unrelated setting cannot broaden old consent. An actual generic autonomy change also discards a copied Manual false marker.

commandReceipt(command, commandId) only inspects that original exact profile-owned command: committed includes its canonical result; pending and unknown are not success or permission to resend. Lost mutation replies are reconciled once against the original authenticated service/store, without re-executing the command. Local edits remain intact.

For a cold native compound start, capture the immutable command and an explicit command ID before dispatch. If its HTTP acknowledgement remains pending while the service performs the existing bounded native source revalidation, inspect only that original receipt within the same operation bound. Do not send another start, use a later input or interpret unknown as a committed workflow. This does not extend mutation, VM, script or model timeouts.

Reads use the service's 30-second deadline plus a separate two-second delivery allowance, rather than an unrelated shorter transport cutoff. An expired read cancels/discards its original source and returns query_timeout; it does not disconnect healthy editing or silently rerun a tool. Electron forwards the same deadline and receipt route. DraftEditor resumes only canonically undispatched autosaves after checking the original fresh revision; peer changes remain conflicts and unknown dispatched saves or input submissions are not replayed. Dispose editors to release their reconnect subscription. Late SSH original-result grants survive restart without converting their original partial turn into success.

git.status/branches/log/show/diff(sessionId, ...) and git.preview(sessionId, action) resolve the actual Local project/worktree. git.execute(preview, confirmations, true) uses the existing independently retained Git job pipeline; inspect git.wait/operation rather than treating admission as success. The finite GitAction union includes branch creation, current-branch rename, clean switch, exact-file stage/unstage, selected staged commits, a new current-tip revert commit, push, rebase and tags. Selected commits reuse the existing private-index pattern and preserve the real index, unrelated staged files and unstaged bytes; they do not borrow the artifact helper's different new-branch publication semantics. Normal pushes also compare the captured destination SHA/absence, without granting non-fast-forward writes. Managed rename binds document.managedBranch and atomically updates the original workspace/change-set name without changing root/base identity. Existing managed roots cannot be switched to another change set. A partial metadata acknowledgement requires separate exact user inspection and metadata-only workspaces.reconcile; it never reruns Git or relabels the operation successful. git_read and git_write expose the same capabilities to the actual model catalogue; ordinary /git commands execute through the original service queue. Unsupported Remote/Sandbox/group/Home execution never borrows a Local checkout.

tools.command(sessionId, jobId, offset, targetSessionId?) reads the original watch job. Another session needs an actual coordination grant. Its typed data.source distinguishes live owned tail, retained result and unavailable; missing wall time/output stays null. tools.acknowledgeCommand requires the exact returned inspection digest and actual-user confirmation; partial work does not become successful. Resume stays separate.

coordination.read(sessionId, input) selects list, inspect, transcript, inbox or the child's original captured parent snapshot. The discriminated data.action carries actual public state/plan/question or a UTF-8 page/digest. Use that digest for continuations. No hidden reasoning, private consoles, credentials or unbounded history expansion is authorized.

const review = await sdk.coordination.preview(parentId, childId);
// Display both actual bindings before an explicit user grant/revocation.
console.log(review.parentBinding, review.childBinding);
await sdk.coordination.grant(parentId, childId, review.digest, true, true);
await sdk.coordination.message(childId, parentId, "An advisory observation.");
await sdk.coordination.control(parentId, {
  action: "dispatch", targetSessionId: childId, text: "The explicitly selected task.",
});

Messages retain actual user/model/service origin. Advisory delivery does not consume drafts, answer/approve or launch paid work. Fresh delivery and queued task admission require the original grant/root proof; stale messages remain inspectable with a diagnostic. Dispatch is explicitly metered work under the child's current controls; stop binds expectedTurnId, including null before admission. Actual question/approval actions use their original owning APIs. Live native coordination is unqualified, never a Local fallback.

workflows.start(sessionId, "review" | "security" | "performance" | "debug", prompt, expectedDraftRevision?) uses the existing prompt admission path. Draft consumption is an exact optional CAS; unrelated drafts stay intact. The four lowercase shared slash presets investigate/fix within current policy. Shared /tools, /tool, /tool-result, /state, /watch and /coordinate also reach CLI/TUI/desktop; CLI accepts the corresponding non-slash names with --session ID. See setup usage (not public yet).

Agent command output

agentTerminals.list(sessionId, { before?, limit? }) returns original run_command requests/results for that exact profile/session, not User or Global consoles, other tools, workflow jobs or private model context. agentTerminals.read(sessionId, commandId, { offset?, limit?, tail? }) returns up to 16,384 retained UTF-8 bytes. Follow nextOffset, or request tail: true without an offset. The tail starts on a complete code point; null output is unavailable, never empty successful execution. Original environment and outcome stay attached to the command, regardless of current settings.

The model executes through run_command and can request the separately approved read-only read_agent_terminal list/read capability. It has no access to private console input/output and no interactive stdin route. Each command owns its existing bounded PTY; this is not a persistent shell or new executor. Policy changes and cancellation invalidate held reads before source return.

CLI agent-terminal list [SEQUENCE ID] --session ID and agent-terminal read COMMAND_ID [UTF8_OFFSET|tail] --session ID share /agent-terminal list/read in desktop/TUI. Opening or reading the Agent view never starts a process/model or adopts a saved PID. Schema 46 changes no SQL layout and preserves original retained bytes/receipts on upgrade.

Retained chat activity

activity.list(sessionId, { before?, limit?, toolName? }) returns up to 100 exact source entries and public-message positions. sequence places an operation in the conversation; updatedSequence follows its latest observed event. Pagination uses the returned nextBefore sequence/ID cursor, so a late result for an old operation returns in the recent page without moving its original transcript position. The ID disambiguates operations updated by the same cancellation event. current separately returns up to 100 running/waiting entries with an exact currentCount, so history pagination cannot hide an old still-running call.

activity.read(sessionId, activityId, "arguments" | "output", { offset?, limit?, toolName?, tail? }) reads the original session-scoped source, up to 16,384 UTF-8 bytes per page. Follow content.nextOffset; null content means unavailable, not empty success. Output size is retained response bytes, not total process/network I/O. Before a final result, outputBasis: "retained-tail" explicitly labels bounded captured output; it cannot become complete process output or a success receipt. activity.turn(sessionId, turnId) returns original timing, outcome, models, context evidence and all-role owning-turn budget totals. activity.response copies public assistant text only from the authenticated snapshot.

conversationNavigation(snapshot, sessionId) derives chronological ConversationNavigationEntry values from already retained public prompts and actual-user structured answers, without a query or mutation. Each opaque ID binds profile/session/source identity; messageId and messageIndex locate the original source, and answer entries retain questionId, question text and exact user answer. Original model turnId values are preserved. Missing sessions are explicit errors; tool approvals, queued prompts and model/decision-provider answers are excluded. The same browser-safe selector serves main/side desktop navigation and other SDK clients without another service endpoint. The current runtime still requires its matching service protocol for per-question side refresh and the other shared APIs.

Snapshot.sessionTelemetry[sessionId] already contains original turns, current budget or its explicit budgetDiagnostic, live estimate, and recorded context. These service-owned views are reconstructed from retained events, messages and original budget entries, updated through normal sequenced snapshot refresh, and scoped to the SDK profile. Opening a display needs no activity.turn, budget.status or session.context query. activity.turn reuses the saved view. Deleting a session removes this view; independently retained accounting survives.

UsageEstimate separates estimated input/visible output and captured-rate USD from reported quantities and held capacity. Original turn windows do not change when the next working window is edited. Context uses the last visible model's retained input estimate plus its visible output; unsent draft text is excluded. knownCacheReadTokens/knownCacheWriteTokens and the corresponding unknown-call counts preserve partial totals without treating missing reports as zero. Explicit zero needs presence evidence; positive normalized counts do not depend on transport presence flags. No private role prompts or reasoning are exposed.

useSessionActivity in moguri/react provides scoped, non-overlapping refresh, earlier-page loading and stale-response isolation. No refresh runs a model, tool, provider metadata lookup or terminal. Thought sources are already-public provider reasoning only; request time is not separate thinking time. Its optional fourth toolName argument narrows the service-owned view and its scope key; it is not an execution grant. Successful unchanged activity reads also survive a chat/dashboard remount in a bounded 16-scope cache owned by the exact SDK client/profile/connection. Draft edits and title-only changes do not invalidate retained operations. Relevant turn/message/usage/operation changes still refresh, and active pending work keeps its existing bounded polling. Earlier loaded pages stay with their own scope. Disconnect, connection replacement and session deletion evict their cache entries; errors never become empty successful histories. This is a transient read cache, not model context, execution authority or durable history.

CLI activity list [SEQUENCE ID], activity turn TURN_ID, and activity read ACTIVITY_ID arguments|output [UTF8_OFFSET] require --session ID. Shared desktop/TUI /activity, /activity before SEQUENCE ID, /activity turn TURN_ID and /activity read ACTIVITY_ID output [UTF8_OFFSET] use the same API. Schema 45 adds only the atomic, actual-user skill.used event/source grant and a transactional version upgrade; existing SQL layouts, ciphertext, receipts and sanitized independent telemetry remain unchanged.

Shared interaction APIs

settings.values.interactions contains confirmSessionAttachments and confirmTerminalClose, both defaulting to true. Use the existing optimistic settings.update or settings.reset("interactions", revision); these settings are profile-scoped presentation preferences, never tool or environment grants.

sessions.reorder(sessionIds) atomically saves one complete current sibling set. Project, group, parent, pin and archive scope must match, with every captured revision still current. compareSessionOrder gives the same stable order used by both clients. CLI session reorder ID... and shared /reorder-sessions ID... call this operation, without reparenting or resuming anything. The explicit main-line form sessions.reorder(projectId, parentSessionId, groupId, archived, entries) also remains supported, with exact caller-captured revisions for its complete sibling set. Direct valid sessions.organize(id, { order }) updates remain available.

attachments.projectPath(sessionId, projectId, relativePath) resolves an explicit Local project source and the current session's bound Local worktree when applicable. attachments.localPath(sessionId, absolutePath) distinguishes regular files from folders without granting model filesystem access. Capture a file with attachments.file; folders retain preview/digest/confirmation. Protected paths, stale managed roots and project denials are not bypassed.

githubPreview / github additionally accept #137, owner/repo#137 and @owner/repo/path. The first needs the current project's GitHub upstream. access: "auto" selects the Local controller's CLI or disclosed public-only access; the existing default remains "public" for SDK callers. Exact remote text bytes, base64, Git blob hash and GitHub provenance are checked before retention. Files are UTF-8 only, up to 128 KiB. The review digest binds actual access provenance as well as source content and destination. This is a disclosed client-attachment boundary, not a substitute for pinned-SSH metadata reads.

The low-level compatibility method terminal.openGlobal(cols?, rows?) opens a Local console in configured canonical HOME. Its binding has null session, project and workspace IDs and the active profile's authenticated Local owner. It neither inherits a selected project's root nor depends on its retention. Protocol 60 retires Global Terminal UI and CLI/slash creation with an explicit error. Existing null-session consoles remain in terminal list and /terminals list for exact inspection/reconciliation/close. terminal.openGlobal(root, cols?, rows?) retains the explicit-root SDK compatibility overload. Its binding retains the actual captured root; it does not substitute a project, session or configured SSH root. Existing terminal.open(sessionId) keeps its exact project/worktree/SSH root. Closing/hiding the desktop pane detaches; terminal.close(id) terminates. Reconnection/restoration never creates a replacement or replays input.

terminal.run(sessionId, command, signal?) is the !COMMAND composer shortcut: it types one line plus Return into the chat's running user console (project folder, managed worktree or captured Home), opening one only when none is running, and returns { terminalId, root, opened }. It never creates a message, steer, queue item or model call. parseShellCommand(text) returns the command for a draft that starts with !, or null. Details: shell lines (not public yet).

sessions.organize(id, changes, expectedRevision?, confirmDetach?) requires the final true acknowledgement when removing an existing parent and this profile's interactions.confirmSessionDetach is not false. It does not bypass revision, same-project, active-work, cycle or model-owned-subagent guards. Desktop drag/menu/parent-selector detachment uses the same native review; remembered opt-out is a profile-owned settings edit, not an approval grant. Missing legacy preferences normalize to true and reset with settings.reset("interactions", revision). Schema 60 adds the transactional session_navigation_schema marker without rewriting retained payloads.

The original desktop schema-44 marker is additive; legacy confirmations default to asking, legacy session order derives from creation, and historical data/grants retain their original encryption and identities. Local project names are safe unique identifiers; normalization never renames filesystem directories.

Retained-state upgrades

Protocol/database 68 requires composer_workflows_schema and exact retained side-prompt command origin. Marker/version insertion is atomic; failure leaves the old state reopenable, current corruption is not repaired, and original ciphertext, grants, receipts and accounting are unchanged.

Protocol/database 67 atomically adds side_context_schema and rejects missing, corrupt or prematurely relabelled markers. Older ciphertext, receipts, creation snapshots and accounting remain unchanged. The first new side question captures its actual original main source under the child's grants; old turns are not replayed, rewritten or granted another paid call.

Protocol/database 66 atomically inserts retained_telemetry_schema and advances the version. Missing/corrupt current markers and premature older-lineage markers are rejected without repair or partial writes. The upgrade preserves original ciphertext, grants, receipts, totals and unknown holds. Startup recovery may append existing budget.recorded events for the same settled call only when its retained original model identity and token totals match exactly. It never infers absent zero counts, reprices with new rates or repeats a completed repair. Unqualified historical result formats are diagnosed without blocking recovery or inventing counts. Stopped runtime snapshots preserve final root-owned capacity without reading closed stores; they cannot authorize another call.

Protocol/database 56 adds the strict transactional browser_control_schema marker and reviewed upgrade from an older running service. Native browser leases/control never persist or replay. The genuine schema-55 migration, interrupted insertion and corrupt-marker cases preserve exact encrypted events, keys, receipts and remembered model selections. Protocol 55's profile-root preference ownership remains unchanged.

Protocol/database 54 adds the versioned session PR observation marker after the converged 53 history. Marker insertion/version advance are transactional; insertion failure rolls back and current missing/corrupt markers refuse reopen. Legacy links keep missing draft state unknown. No ciphertext, keys, grants, drafts, command receipts or historical lifecycle outcomes are rewritten.

Protocol/database 53 converges main-line versions 44-52 and the independently numbered desktop versions 44-46. It identifies desktop provenance by the retained desktop_interaction_schema marker, not by guessing from the version. Its one transaction validates or adds the required entry, preferences, browser capture, sounds, application, storage, updates, session interaction and managed Sandbox markers and advances the version only after all succeed. A known desktop store previously opened by main also retains that original provenance.

Migration never rewrites encrypted history, keys, source grants or receipts, replays commands, starts a model or changes retained approval/accounting actors. Missing markers in a main-line store and invalid provenance/marker values fail without partial writes. Generated coverage includes both lineages, the known partial crossing, insertion failure, corruption and an actual service reopen. Restart matching clients and service while retaining the original state root and encryption backend; never delete state to make an upgrade succeed.

The repository's warning-free npm ci uses root-level compatibility overrides. npm does not inherit a dependency's overrides, so a minimal external SDK host can still report the upstream whatwg-encoding/node-domexception deprecations. To apply the same verified Node 26 policy without changing unrelated host dependencies, the embedding application's root manifest can use:

{
  "overrides": {
    "moguri": {
      "encoding-sniffer": "1.0.2",
      "node-fetch": "npm:node-fetch-native@1.6.7"
    }
  }
}

Session interaction contract

sessions.reorder(projectId, parentSessionId, groupId, archived, sessions) requires the complete sibling set as {sessionId, revision} entries. It checks all revisions before appending the existing session.organized events atomically. Session.order and the browser-safe compareSessions helper provide shared presentation order with pin priority; they do not change worker admission priority. Existing sessions.organize(id, {parentSessionId}, revision) keeps same-project, no-active-reparenting, model-subagent and cycle/depth boundaries. No move transfers model context, roots, Env or permissions.

settings.values.retention.confirmArchive and confirmDelete default to true and scope to the current profile. They are routine client-confirmation preferences, not CP permission grants or automatic retention policy. Actual session deletion still requires its existing explicit confirmation/revision and successful owned cleanup.

Protocol 112 adds an optional confirmRunning: true to session.archive, session.delete, sessions.bulk and project.remove (SDK: sessions.delete(id, true, revision, children, { confirmRunning: true }), sessions.bulk(preview, true, { confirmRunning: true }) and projects.remove(id, true, revision, artifacts, { confirmRunning: true })). When the selected trees hold a running session (an active or waiting turn, or a running owned job), the service refuses without it with session_running (409) and changes nothing, whatever confirmation preferences are saved. Clients send it only after showing the user the browser-safe runningSessions(sessions, jobs, rootIds) warning; runningSessionNames formats it.

questions.skip(questionId, revision) records the actual user's explicit skip (answer.skipped: true, text Skipped, schema 107). The model receives { answer: null, skipped: true } with guidance that a skip is not consent, and no answer artifact is retained.

questions.answerOther(questionId, text, revision) explicitly records a real user's alternative, including for a strict-choice question. It does not add a model-offered choice, expand automatic technical-choice delegation or consume the chat draft. questions.answerDraft(id, revision, true) is the separate explicit Other path that atomically consumes only the exact saved text revision. Ordinary answer/answerDraft retain their original validation. CLI moguri question answer-other ID ANSWER_FILE --revision N and shared /question other ID REV TEXT use the same endpoint. Neither operation grants tool/Git permission.

The owning worker's existing task_progress tool accepts action: "plan" with a title and two to fifty distinct {text, status} steps (pending, in_progress, done). task.plan_updated and Session.taskPlan retain its actual model/step/call, binding hash, revision and turn. progress.plan is null for another task/root; polling and ordinary messages cannot create a plan or start another inference. The desktop shows this checklist only in Plan.

Resume admits one queued prompt per settled owned turn. New explicit stop intent uses turn.stop_requested.payload.holdQueue to retain undispatched prompts through restart without changing legacy event interpretation. Explicit Interrupt keeps its own next-turn semantics; cancellation and unknown accounting never become completed work or authorization for a replay.

Document attachments

attachments.file(sessionId, path) automatically extends existing source/text and image selection with content-validated .pdf, .docx and .xlsx. attachments.document(sessionId, path, { captureId, expectedRevision? }) requires a supported document format; cancelDocument(sessionId, captureId) stops that exact active capture, not a turn or another client's work. The service owns admission, extraction and the optimistic draft transaction.

const captureId = crypto.randomUUID();
const captured = await sdk.attachments.document(sessionId, "/explicit/report.xlsx", { captureId });
const descriptor = await sdk.attachments.read(sessionId, captured.id!);
const page = await sdk.attachments.readDocument(sessionId, captured.id!, {
  sheet: "Sheet1", range: "A1:D20", limit: 4096,
});
const matches = await sdk.attachments.searchDocument(sessionId, captured.id!, {
  query: "literal text", limit: 5,
});

Reads accept a PDF page, extracted section, or exact XLSX sheet with an optional ascending A1 range. Their UTF-8 offset / nextOffset applies only to that exact selection's JSON-lines view. firstLocation / lastLocation preserve provenance even across a split line. Search cursor / nextCursor and inventory offset / nextOffset are independent. Reset pagination when changing the selection/query.

listDocuments(sessionId, { offset?, limit? }) returns bounded descriptors, without bodies or workstation paths. The model's separately approved list_documents sees admitted documents only, including after compaction. User preview APIs can inspect retained draft/queue documents. original() explicitly returns the bounded original as canonical base64; ordinary read() returns a document descriptor/status, never its full extraction or original.

All these schemas, types and calls remain browser-safe. Only explicit Node runtime creation loads the parser supervisor; its compiled worker and libraries are included in packed consumers. The document contract (not public yet) defines licenses, resource bounds, encrypted grants, cancellation and migration.

Reviewed platform workflow surface

All commands/queries below use the same authenticated loopback API, immutable profile, optimistic review/revision checks and sequenced events. No new public network API or credential fallback is added. Root/React imports remain browser-safe; Node runtime loading stays explicit.

SDK surface Authority and result
knowledge.save/list/read/history/version Exact Sky session/lifetime or Terra project/work item; profile-wide Glacier only after reviewed promotion
knowledge.promote(id, revision, digest, summary, true) Independent user-reviewed compressed copy, never model acceptance or automatic source mutation
knowledge.rollback/forget Exact original note revisions; per-note encryption grants and non-replayable creation intent survive source expiry without retaining its text
hooks.import(projectId, definition) Bounded turn.start/turn.end definitions, imported disabled
capabilities.history/version/rollback/useSkill Review retained actual bytes, restore disabled content or append a selected skill to an optimistic saved draft without sending it
marketplace.catalog/preview/install Registered repository, full commit and catalog path; complete exact bundle review; atomic disabled install/update/rollback
github.browse/preview/execute/read/history/wait/cancel Explicit Local root and actual selected controller gh account; protected Git/GitHub confirmations and independent original effects
linear.catalog/issue/preview/execute/accept/read/history/wait/cancel Explicit enabled board/team, exact account/entity/revision review, two-way local ticket mapping and retained original results
cache.inspect/prepare/install npm/pnpm/python/cargo/go; exact manifests/locks, resource authorization, advisories and verified immutable bytes; executable builds are not implied
cache.registries.list/save/remove/setToken/clearToken Profile-scoped private resources; secrets stay in the explicit keychain and never enter metadata/receipts
containment.status/requireSandbox(true) Truthful process-group limitation or explicit global qualified-SendBox requirement; no launch, inferred PID ownership or Env substitution

memory.useTieredContext defaults off even in older state that already enabled source-index context. Imports/enabling cannot grant tools, answer a question, authenticate, start paid work, or weaken policy. Session-owned workflow stop propagates to its original job while independently retained operation documents survive source deletion. Unknown remote writes remain partial, never retried from lost receipts or restart.

Desktop Settings, the dedicated CLI and shared TUI/CLI/desktop slash handlers all call these APIs. Examples and exact errors/lifecycle limits are in platform workflows (not public yet), GitHub (not public yet), Linear (not public yet) and dependency cache scopes (not public yet).

Shared preference maintenance

Protocol 78 adds the transactional theme_catalog_schema=1 marker and the Rose, Terminal, Aubergine, Ember, Monochrome, Vaporwave and Crystal palette IDs. Existing Moguri/Ocean/Orchid IDs, saved Custom values and factory Dark are unchanged. themePalettes, ThemePaletteSchema and appearanceColors expose one browser-safe catalogue; sdk.slash(sessionId, "/theme crystal dark") uses the existing revision-bound settings API, without inference. /theme list inspects the catalogue and palette-only changes preserve the selected mode. Desktop and TUI render those same tokens. No new event kind or preference store is introduced; rollback/restart and strict lineage checks preserve retained data.

Protocol 45 preserves old event/control bytes and explicitly saved retention values while filling new nested defaults. settings.update/reset includes typed guidance, named/custom appearance, default permissions.defaultDecision, optional session verbosity, lifecycle and existing-daemon integration settings. Global/project guidance is recorded in actual future prompt snapshots. runtime.status() reports the encrypted directory and real owned idle-sleep state; runtime.retryPower() retries only that original helper, never a model.

projects.repositories(id) is a bounded, explicitly Local, non-link-following inspection. With one completely verified repository, including a nested root, its upstream is the remote that repository's live Git configuration selects (gh repo set-default choice, then origin, then the only remote; never the checked-out branch's tracking remote), or null. Project settings never store an upstream; a legacy repo.upstream is ignored and dropped. Incomplete/denied/multi-repository layouts do not guess or rebind the session's workspace.

integrations.githubConnection() explicitly verifies the controller GitHub CLI account without Copilot/update credentials. linear.connection(false) reads only credential presence; linear.connection(true) verifies the actual account and workspace without inventing a project/team. integrations.sqlStatus() makes only the enabled, explicitly configured existing daemon's bounded health read. These observations do not grant files, tools, repository writes or model access.

Decision-provider development surface

decisions.status(sessionId) reports actual compatible provider readiness, privacy and output limits without inference. decisions.list(sessionId?) reads independently retained requests; decisions.read(id) returns the exact original rubric/state/policy, real model actor/step, raw result and validated advice. decisions.stop(id) stops only that original one-shot owner, not another parent turn. There is deliberately no public evaluate, answer, approve, retry or permission-grant endpoint.

settings.decisions defaults disabled with no selected model. Save an explicit bounded-model policy and available canonical model ID, then separately choose Autopilot Max in session controls. Fixed and kupo Single model selection stays independent. Hosted inputs require separate consent; the root-less Local worker uses actual all-role token/USD admission and existing finishing holds. Protocol85 additionally binds tool-less subcalls to the original SSH/native parent using version-2 DecisionRecord/DecisionDocument and OwnedModelTransport. Their env, exact execution/worker/peer or guest/root identity and owned-role-acknowledged cleanup cannot become a Local record or proof of parent exit. An unchanged readiness read starts no inference. The dedicated Jev contract remains unqualified because the current API cannot enforce a positive output-token bound. Remote/native Max never executes on the Local controller as a fallback.

Existing scheduledPrompts.create can perform model-free native source preparation under the explicitly enabled managed policy before its atomic ghost/draft admission. SandboxWorkspace.preparation.version === 2 binds the original scheduling command/digest and saved draft revision/digest; it never claims a model turn or restores a failed stage.

Version-2 WinddownRecord/WinddownDocument keeps planned scope separate from the actual transport bound once at hold transfer/model start. winddown.read returns its original aggregate-only model input/result. SSH/native reports cannot acquire Local Git fields or completed publication state. A changed current session Env cannot adopt them through commitPreview. Exact late inspection may fill an admitted partial step's raw observation and settle its original charge, but cannot change terminal outcome/cleanup, validate advice or restart the parent. Deleted reports are not reconstructed.

Error Meaning and recovery
decision_transport No exact active pinned parent or qualified provider scope; review the selected Env, never substitute a controller worker.
decision_late_owner Original model/role/peer/root or settled owner does not match inspection; preserve the original unknown hold and inspect its actual owner.
winddown_late_owner Original complete finishing hold/start/transport is absent or changed; no new hold, model or Git effect is inferred.

These use the existing authenticated, immutable-profile query/command and receipt surface; no public paid-evaluate, replay or authority-grant endpoint is added. See owned model transports (not public yet).

Shared /decisions status|list|read ID|stop ID confirm-stop|set POLICY_JSON and CLI moguri decisions status --session ID, list, read ID, stop ID, or set POLICY.json --confirm-review use the same authority. Configuration starts no inference and grants no tool authority. Desktop exposes Decision providers settings, service-derived composer readiness and Artifacts / Decision-provider history; TUI edits report metadata only. Automated technical answers retain actual provider provenance and independent original evidence even when the decision report/source session is deleted. Unknown charges stay held; scores/confidence are not calibrated permission. See the owned decision contract (not public yet).

Native SDK development surface

The primary managed flow uses sandbox.setup.status() and sandbox.setup.review(version?) to inspect the actual supplied runtime/image, network/workspace policy and exact installer location. After actual user review, call sandbox.setup.apply(review) and observe its original ID with sandbox.setup.operation(id) or sandbox.setup.wait(id). Administrator approval is requested only when the exact root-owned release is not already installed. sandbox.setup.cancel(id) targets only that owned operation. No setup call starts a model or silently selects a provider, Env or new runtime version.

sandbox.setup.check() observes the fixed public SendBox release feed; sandbox.setup.prepare(version) downloads and verifies that exact eligible archive (0.2.7 or newer) and prepares a no-script package for a separate review. The app bundles 0.2.7 and a current-protocol worker OCI archive with Linux Node/native dependencies. Source/Node embeddings may pass platform.sandbox.distribution explicitly. An accepted retained distribution is reused only with its original digest; there is no app-directory scan or mutable image pull. Factory defaults do not rewrite an explicitly retained older version. Releases older than 0.2.7 are unsupported: such a saved selection still loads but is blocked before native execution. sandbox.setup.status() says so in its diagnostic and sandbox.setup.review() without a version reviews the bundled release, disclosing the replacement; review("0.2.6") is refused. Nothing changes until that review is applied, and there is no Local fallback. A changed bundled vendor or any of its exact pins invalidates the producer cache even when the worker payload is identical; actual artifact hashes are still reverified.

After managed setup approval and explicit Env selection, ordinary Send prepares the bound project/worktree privately and automatically. Engine-only qualification has no dependency on an unselected Copilot account or endpoint; turn admission resolves only the actual selected provider. Root-less chats require no empty preview. Complete regular-file snapshots support 20,000 files, 256 MiB total and 32 MiB per file, including binary/large sources, without expanding model context or silently choosing a subset. Protected, ignored and denied paths stay out. Successful private changes persist; verified after-state restoration creates a new owned stage after rollback. Source publication remains separate. Selected-provider HTTPS endpoints and bounded public CNAME chains are captured per original execution; fetch_page reads only approved public pages inside the guest without controller credentials or a Local fetch.

sandbox.status() reports actual configuration-bound readiness. Explicit advanced sandbox.probe() verifies the configured root-owned release, immutable workload and real guest controls/cleanup. Configure settings.sandbox only with independently reviewed executable/bundle/key paths, SHA-256 pins, release/trust-root/sequence, workload/worker/bridge digests, resource caps and canonical DNS hosts or explicit *.domain.com tool rules. Wildcards match subdomains at any depth, not the apex or suffix lookalikes; exact entries remain exact except github.com, which delegates GitHub Meta domains and IPv4/IPv6 ranges including shared-cloud addresses. The SendBox host fetches them into one machine-wide cache, revalidates it at most hourly and seeds each guest before readiness; guests never contact GitHub Meta. The service binds that broader delegation into setup review's diagnostic/digest, and activation requires the existing explicit user/network acknowledgement. These rules never substitute for actual provider URL/CNAME admission or grant provider credentials. The captured scope retains literal reviewed rules alongside exact provider/alias hosts, with a 32-entry limit on Moguri's logical rules. That limit is not a claim about the size of the upstream Meta expansion. configPath must be null to select the managed deny-first policy; legacy policies are never silently replaced. Copilot access is opt-in, with a separate actual cold guest networking check. An observed alias is not a grant. Automatic aliases require the separately approved managed policy.

For optional advanced exact-file staging after selecting Sandbox, use sandbox.preview(sessionId, paths) to inspect an exact source set, then sandbox.prepare(sessionId, paths, preview.digest, session.revision) only after user review. A project-free chat uses [] and retains a null model root. The physical stage is private and independent of the source checkout; this review is not required by managed automatic staging. Ordinary SDK send/queue/stop/approval APIs retain their shared authority. Qualified native read_file calls can page scoped pasted files through the controller broker.

sandbox.execution(id) and sandbox.result(id) inspect the independently retained original owner and bounded signed after-state. sandbox.reconcile(id) explicitly stops/inspects only that original signed guest and reconciles authenticated late receipts; it never launches a VM, repeats a model/tool call, adds completed solver context or upgrades a partial turn. Unknown telemetry continues holding capacity. Private output files are capped at 200/2 MiB; excluded, protected, binary and oversized paths remain disclosed, not truncated. sandbox.stop(executionId) stops only that exact currently owned native turn; it cannot cancel a later turn merely sharing a session. Native project-file capture reads the actual private stage, never the Local source checkout.

sandbox.publicationPreview(executionId, paths, repository?) reviews up to 20 selected text outputs with a 32-KiB patch and 64-KiB complete document against original Local source bases. Its limits exposes both exact byte boundaries. Separately confirmed sandbox.publish(executionId, paths, preview.digest, execution.revision, repository?) starts an independently owned user copy job. Inspect it with sandbox.publication(id)/sandbox.waitPublication(id); stop its actual job with jobs.cancel(jobId). This is explicit user text publication, not a Local agent fallback or a model acceptance/permission decision. Current root, branch, HEAD, folder rules, hard write denials and leases win races; index/HEAD and unrelated edits are preserved. Partial writes remain inspectable and cannot be replayed. Publication snapshots survive original session/report deletion. There is no implicit commit, branch, source deletion or binary/deleted-file publication. Native console/MCP/memory/subagent/evolution and plan-write transports remain unqualified rather than falling back to Local. For captured groups, repository is mandatory and chooses an exact original ID or unique captured name, never a first member. Paths stay member-relative. Every original root/policy/HEAD/file set is rechecked and leased. Version-3 input and version-2 result/publication records preserve the map; original v1/v2 single-root inputs and v1 results/publications are not reinterpreted.

CLI sandbox preview/prepare PATHS.json --session ID reads an explicit bounded JSON path array. Preparation needs its exact --digest, session --revision and --confirm-review. Publication uses sandbox publish-preview RUN_ID PATHS.json, followed separately by sandbox publish RUN_ID PATHS.json --digest SHA --revision EXECUTION_REV --confirm-write; Ctrl+C requests the original copy job's stop. publication, publication-stop and publication-wait inspect/cancel that retained owner. Shared CLI/TUI/desktop /sandbox commands print exact confirm-stage/confirm-publish commands after preview. No text prefix or model answer is treated as confirmation. Group CLI publication adds --repository ID to preview and publish. Shared /sandbox publish-preview RUN_ID {"paths":["file"],"repository":"ID"} includes that exact original ID in its generated confirm command; the legacy paths-array syntax remains valid for single-project results.

This is an alpha API. Qualified 0.29.0-alpha.1 uses protocol 35. Qualified 0.28.0-alpha.1 uses protocol 34; the frozen qualified 0.27.0-alpha.1 uses protocol 33. Both deliberately reject incompatible running services. Remote execution requires the matching SSH worker for exact user plan operations, reviewed compaction, model telemetry, explicitly granted MCP and owned user consoles. The 0.21 delivery implements session-bound Local/SSH memory through the same SDK. Its exact independently installed archive and actual packaged runtime pass index/search/MCP/original-intent/restart/CLI/TUI qualification. The qualified 0.22 delivery uses protocol/database 29 for the shared Local reviewed-candidate workflow (not public yet), following the protocol-28 event/retention foundation and private compound/file prerequisites. Its exact SDK and actual packaged app are independently qualified; setup (not public yet) preserves immutable delivery identities. Public kupo remains the qualified Single subset. The qualified 0.23 delivery uses protocol/database 31 for independent planned capacity and one bounded Local owned draft (not public yet) with shared generation/review/stop inspection, without enabling public finite kupo. Its exact installed SDK and actual native runtime pass independent generation/staging/application/restart qualification, including missing original receipts; setup (not public yet) records its immutable identities. Qualified 0.25 uses protocol 32 for independently retained role observations (not public yet), read-only SDK/CLI/native inspection and version-4 history. This adds no model-start, acceptance or public compound workflow command. Its exact installed archive and actual bundled runtime pass role inspection, source deletion/reopen, version-4 export and deletion-intent qualification without inference; setup (not public yet) records immutable identities. Restart old running services explicitly; do not delete their state. The 0.26 source reuses protocol 32 for an internal actual owned-role executor over complete source/model/policy/input envelopes. Its Node controller primitive is privileged and not a public SDK/HTTP/MCP workflow creator. Client roleSequences remains read-only; family/quality/acceptance and finite kupo stay separately gated. Qualification status is recorded in setup. Qualified 0.27 uses protocol 33 for canonical final-role proposal inspection and review-bound candidate origin. candidates.roleProposal(id) reads the exact final proposer without a model/root lookup. candidates.preview(session, stage, patch, {roleSequenceId:id}) binds its origin into the review digest; pass that same reference to stage as its optional fifth argument. Existing generation-ID strings remain compatible. Candidate copies retain sequence/role input and raw-result grants independently; their exports use version 5. Editing loses verified attribution, and applying still needs a separate actual-user review. This does not expose a public compound workflow creator. Restart incompatible services explicitly, never delete their state. Its exact installed SDK and bundled runtime are independently qualified; setup (not public yet) records immutable identities. Frozen qualified 0.25 remains protocol 32. The qualified 0.28 delivery adds explicit models.evidence(modelId) inspection. Its version-1 provider-declared report is ephemeral and does not rewrite ModelInfo, select a model or grant lineage/quality/approval. The additive schema-34 marker preserves actual schema-33 candidate origins and independent raw-copy grants. Its exact installed SDK and actual bundled default Copilot adapter use the same generated, memory-only keyring/catalogue qualification, not a substituted adapter or a personal account. Setup (not public yet) records frozen native/SDK identities and limits. The 0.29 delivery adds optional exact output/context contracts to the internal owned executor, version-2 retained inputs and immutable input-version binding. roleSequences.contract(sequenceId,index), CLI roles contract ID N, shared/native TUI /roles contract ID N and desktop Artifacts inspect derived declared checks without inference, approval or public workflow scheduling. Original version-1 data is not retrofitted. See the contract (not public yet). Its exact installed SDK executes four actually metered contracted roles; actual native readers derive their original checks with model preparation forbidden. This does not enable public conditional pattern scheduling or attest model quality. Current state migrations preserve schema-1 through schema-33 history, sessions, drafts, receipts, blobs, indexes and retention compartments. Migration 5 adds optional model controls without resetting prior defaults. Migration 6 adds nullable project scope, reviewed configuration and OAuth/attention state. Restart a previously running alpha service explicitly with node bin/moguri.mjs service restart; do not delete its state.

The issue-17 source uses protocol/database 36 for scoped pasted-text file descriptors and optional queue-edit attachments. Schema 35 upgrades without rewriting historical events, receipts, encrypted grants or arbitrary legacy working-window settings. Unsupported legacy windows remain visible and block inference until explicitly corrected. modelContextWindows(model) and sessions.context(id).context.windows share maximum/half or genuine declared choices. attachments.paste(id,text,selection?,draftRevision?) atomically captures exact pasted text into the current draft; DraftEditor.paste also preserves unsent/conflicting local edits. The existing authenticated worker read_file broker exposes bounded pages/search without injecting the whole file into model context. These are source capabilities, not a claim that any earlier immutable SDK/app archive was rebuilt or that issue 17 is complete. The 0.18 source adds authoritative Remote MCP (not public yet). Explicit peer/resource grants are deny-by-default. Source SDK model/external calls now use the owned SSH worker, encrypted intent/result retention and no-replay crash reconciliation; shared native clients share the same review and inspection APIs. Exact archive identities and qualification are recorded in setup (not public yet); older immutable deliveries are not repacked. The qualified 0.19 delivery extends this with protocol-25 immutable Remote owner/binding state, schema-preserving migration and original-PTY recovery across service/SDK/CLI/OpenTUI/Ghostty. Its exact independently installed SDK and actual packaged runtime pass the same Remote lifecycle, no-replay and ordinary-stop contracts. Prior qualified archives remain immutable. Qualified 0.20 adds explicit Remote GitHub repository metadata through the captured SSH account, with peer/root/build provenance and no controller account fallback. Its exact installed SDK and actual packaged clients pass separate account/restart/CLI/TUI and native qualification.

Build and consume

npm ci
npm run build
npm pack

Install the resulting moguri-<package-version>.tgz in a Node 26 consumer with npm. Exact delivered filenames/checksums and qualification records live in setup (not public yet). A newer development manifest is not another qualified archive until its exact bytes are independently checked. The package is private and is not published to the npm registry. It includes compiled SDK modules, declarations, CLI, workers, clients and the pinned local speech runtime, but no speech weights. Native dependencies must match the consumer's platform. Use npm's normal dependency installation, not --ignore-scripts, for an operational CLI. With npm's script allowlist enabled, review npm install-scripts ls and approve this known Moguri package plus its pinned Node/node-pty native installation steps. A file-tarball dependency is approved by package name rather than a registry-version selector. Do not approve unused provider lifecycle scripts.

For an installed file tarball, complete its reviewed native-helper setup with npm install-scripts approve moguri then npm rebuild moguri. The approval command resolves the package name to that exact file dependency; an unapproved install notice is not proof that its postinstall ran.

Import Surface
moguri Browser-safe MoguriSdk, typed protocol, defaults, DraftEditor, ASCII identity
moguri/node connectMoguri, createRuntime, private service discovery and explicit owned-service shutdown
moguri/react Renderer-independent useMoguri subscription hook
moguri/mcp The single outward native MCP server, bound to one session

npm run verify:sdk packs and installs into a separate temporary consumer, type-checks all four entrypoints without the repository's tsconfig, and runs an embedded service with real vector retrieval and native MCP discovery. It also exercises the packed package's actual PTY transport on macOS after explicit script approval and an independent consumer audit. It does not authorize a personal account, record audio or download model weights.

Pass an existing archive to qualify the exact delivered bytes rather than repacking: npm run verify:sdk -- release/moguri-0.17.0-alpha.1.tgz. Current verification also exercises actual installed-worker SSH files, Git/plan reads, dated/per-call telemetry and actual metered compaction with the installed CLI/worker. Historical archives retain their separately recorded qualification; protocol-16/17/18/19/20/21 SSH receipts remain inspectable without reattaching or continuing an old worker.

Connect to the shared service

import { connectMoguri } from "moguri/node";

const sdk = await connectMoguri();
try {
  const settings = sdk.settings.get();
  if (!settings) throw new Error("Moguri is not connected.");
  console.log(settings.values.appearance.theme); // dark by default
  const projects = sdk.getState().snapshot?.projects;
  console.log(projects?.map(({ id, name }) => ({ id, name })));
} finally {
  sdk.disconnect();
}

Connection metadata contains a private token. Never print it, put it in URLs, send it to a model or pass it to plugins. Disconnecting a client does not stop the shared service or its owned work. SDK command IDs are idempotent; a lost response does not authorize an automatic resend.

Embedding is explicit:

import { createRuntime, connectMoguri } from "moguri/node";

const stateDir = "/absolute/private/moguri-state";
const runtime = await createRuntime({ stateDir });
const sdk = await connectMoguri({ stateDir, autoStart: false });
try {
  console.log((await sdk.voice.status()).voice.diagnostic);
} finally {
  sdk.disconnect();
  await runtime.close();
}

Only embed when no other service owns that directory. Importing the SDK alone does not start a service or read credentials. Node discovery does not load the provider/MCP/native PTY runtime; createRuntime explicitly loads its packaged runtime.mjs entry. Default provider initialization uses Moguri's OS-keychain backend; generated providers are injected only in tests.

Shared capability APIs

Facade Operations and boundaries
profiles Root catalog/create/revisioned name-color update/explicit retry-stop/wait, shared global defaults/caps and open(id) returning a new immutable scoped client. No account/data copy or automatic selection.
settings / prompt Get, revision-checked update/reset, effective prompt preview. Prompt edits require explicit risk acknowledgement; running turns retain their prompt digest.
tools Scoped typed catalogue, exact Local user-job admission, public original-result pages, canonical state SQL reads and captured watch inspection. Discovery grants nothing; no model-owner or Env fallback.
coordination Exact original-parent/root grant preview, actual sender messages, bounded public context/progress and explicitly owned child tasks/stop. Navigation nesting and read acknowledgement are not authority.
workflows Lowercase review/security/performance/debug prompt admission under the existing session controls, with optional exact draft consumption.
memory Opt-in index, lexical-vector search, import/symbol graph, explicit project-style facts. Context injection has a separate opt-in.
capabilities Import disabled standard skills/plugins, inspect source, toggle with revision, propose, review and decide against an exact SHA-256.
mcp Paged tool discovery, non-secret auth status, explicit OAuth begin/status/cancel/clear/registered-client setup, user-only keychain credentials, exact approval-bound call and retained result pages.
subagents Explicit opt-in, depth-one tool-less child using the inherited selected model policy and approved parent context. Every role charges its real owner.
voice Local status, explicit licensed download, record/transcribe, stop/finalize, bounded session-owned transcript reading and revision-safe draft insertion.
jobs Wait or explicitly cancel. A wait timeout/disconnection does not cancel or retry the service's job.
sandbox Truthful readiness/configuration diagnostics. Configuration is not proof of a qualified SendBox transport.
issues Local feature/bug/misc board, create/update/move/archive, revision-checked phases and read-only linked-PR refresh.
kanban One special project chat, shared source/visibility preferences, paged local/GitHub work, one actual-user delegated Local task to its PR, retained read/wait/cancel and exact settled-task inspection.
prices Originating-provider API-equivalent references, exact model/name matches and explicit official public refresh; no inference, authentication, historical repricing or billed-cost claim.
cache Local plan inspection, explicit metadata-sharing consent, integrity-verified archive preparation and script-free managed install.
linear Optional team-scoped read-only page import, status and user-only OS-keychain credential setup.
sessions Revisioned controls/modelOptions, local context preview, rename/mode/pin/unread/group/attach/delete, explicit side/agent children and work-item/verified-PR context. Side sessions cannot acquire write authority.
projects Configuration, ordered folders/color, atomic reorder, relocation/removal, scoped Git/source reads, reviewed MCP imports and explicit default-file publication.
prompts / DraftEditor Copy queued/sent text, revisioned editing and explicit held release. send("queue", true) returns the admitted queue ID without starting work.
commands Service-owned slash intake through submit; archived restore preserves its saved draft. read/claim/choose/complete bind original input, root and private client ownership. attach supplies real UI handlers; detachAll awaits teardown without replay.
plans Digest-checked Local/Remote plan read/save and independent snapshots. Remote writes require the reviewed binding and an owned no-model operation; actual saves/info/exact-stop expose partial/recovery outcomes without replay.
artifacts Independent typed text documents, exact source preview/promotion, revisions, optimistic edits/archive/delete and reviewed project retain/export/delete. No automatic instruction or memory promotion.
candidates Model-free Local preview/stage/read/wait and separately reviewed apply/reject/stop; optional one-call fixed-model generation has its own cost/source review, actual draft ledger/provenance and retained wait/stop. Neither generation nor staging approves application or Git publication.
roleSequences Read exact independently retained role intent, original input and one selected raw role input/result; never start a model, grant acceptance or resume partial work.
compound Exact selected-Env source/cost preview/start/read, actual-user stage/test review/deny and exact stop. Local roles remain root-less; non-Local roles retain their actual rooted peer/native parent and zero model tools. Runtime/physical qualification still gates admission. lineageDraft is an unpersisted source claim, never provider inspection, quality or permission. Source application stays separate in candidates.
winddown Canonical readiness and independent selected-boundary finishing holds/input/results/stop. Separate accepted-source/new-branch Git review preserves the original Local or SSH root; native-model work discloses its separately accepted original Local-Git boundary. Exact effect inspection/acknowledgement never completes or replays a partial job. All roles share one ledger; summaries grant no source/Git authority or ordinary continuation.
decisions Exact request/model/rubric/raw evidence, actual Local or original SSH/native parent transport, all-role accounting and one-shot stop. No public evaluate, paid retry, answer or approval endpoint. Only separate explicit delegation can use the real decision-provider actor.
questions Exact owning-turn/revision-bound actual user answers, choice/freeform validation and optional atomic saved-draft consumption. Question routing never grants tool/Git authority.
budgets Cumulative owning-session/profile status, revision-bound hard policy, UTC-filtered/paged role/model/turn dashboard, planned non-call holds, captured rates and retained calls/stream observations. Filters never change admission; unknown usage remains held.
telemetry Independently retained, sanitized tool/MCP outcomes with scoped UTC filters and a known-result failure rate; current-profile key-backed ciphertext sizes, never physical/freed disk usage.
activity Exact session-scoped operation metadata and lazy original arguments/results; public response copy and original owning-turn information. No private reasoning, terminal buffers or recovery from a deleted source.
agentTerminals Original agent run_command requests/results and bounded UTF-8 output/tails. No private User/Global console access, stdin, new execution or implicit persistent shell.
repositories Explicit actual-root preview/refresh/state/revision-bound clear, with displayed GitHub access and immutable future model/tool attribution. No automatic lookup, backfill or permission grant.
compactions Source/model-bound reviewed generation/apply/restore, compact() for /compact, and default-on smart compaction (settings.compaction) through the same worker/ledger. Originals/images remain retained; no history deletion or answer/permission promotion.
routing Actual mode/capability/profile readiness, revision-bound policy and original classifier/role/selected-response history. Explicit Single/Compound stays separate. Finite automatic work requires complete selected-boundary holds/finishing; unsupported image/effort/model combinations stay blocked.
workspaces Explicit Local create/discover/inspect/bind/remove/reconcile/wait and session-bound Git/files reads. Owned directory identity is not a process-containment claim.
terminal Exact Local/pinned-SSH PTY open/read/resize/input/close, one independent Local openGlobal(root) per profile, disclosed defaultRoot(), terminal/owner reconciliation and explicit inspection acknowledgements. Captured env/peer/root survives restart; input/resize bypass durable receipts.
slash / slashCommands One browser-safe low-level dispatcher/catalogue. Frontend text uses commands.submit, not eager slash dispatch. commands.control(sessionId, name, argument) queues one session control (model, effort, context-window, model-settings, kupo-mode, env, autonomy, budget) as its exact single-line slash command without touching the draft, so clients can change controls during a turn. Results are typed session/native-panel/copy/text actions, not client-owned domain state.
suggestions Local scoped preview, exact source digest and explicit generation consent. Analysis uses a normal cancellable/accounted metachat turn.
metachat / configuration Explicit settings chat, non-secret exact proposals, review and human risk/base-bound apply/reject. No model application or automatic enablement.
attention Shared Inbox list/read/delete; questions/approvals remain unresolved until an actual answer/decision, and deleting a notification never deletes its session.
models Profile-owned catalogue(), setProviderEnabled, setEnabled and exclusive selectSource, plus explicit refresh, informational evidence(modelId), always-visible Kupo and resource-bound endpoint keys. Selection and admission use only enabled, available, chosen sources; disabled inventory remains inspectable. No sign-in, inference, host scan, automatic evidence read or substitution.
attachments Explicit local text/images, exact folder/reference/session previews and confirmation, private snapshot reads. Unsupported models preserve context rather than silently dropping images.
remote Explicit pinned-target probe/status, resource-bound endpoint keys and existing-run reconciliation/inspection acknowledgement. No provisioning, key forwarding, Local fallback or side-effect replay.

Native snapshot retries and transport checkpoint review

Protocol86 adds settings.values.interactions.nativeRetryRestaging, factory off. sessions.retry still admits only the last exact retained failure; enabled native retries restore its signed private snapshot and cannot capture new live-source bytes, change Env/model/profile, replay effects or refund unknown calls.

winddown.sourcePreview(id, paths) reads complete exact SSH source: at most 20 distinct paths, each up to 4,096 characters, subject to the actual host's filesystem limits and the complete 128-KiB source/Git review bound. It never uses the shorter artifact-ID bound for file paths or truncates a review. acceptSource(id, paths, revision, digest, true) binds actual-user source acceptance, not Git permission. commitPreview/commit use remoteAccepted:true for that peer or exact nativePublicationIds for already separately accepted native output. The former performs Git only on the captured peer; the latter explicitly uses Local Git at the original source repository and requires current Local policy. New branch, base, bytes/modes and message are separately reviewed.

inspectCommit(id) is read-only and returns exact current source/ref/receipt review data. reconcileCommit(id, revision, digest, true) is separate actual-user acknowledgement of an ended original writer, never an answer, approval, effect replay or partial-to-success transition. read(id).commitInspection retains that observation independently of the session. Unknown or changed source/ref/cleanup cannot release its quarantine or erase its report.

CLI uses winddown source-preview/source-accept, preview/commit, inspect/reconcile; acceptance/reconciliation require exact --revision, --digest and --confirm-review, while Git requires --confirm-git. The shared TUI commands are /winddown source-preview ID PATHS_JSON, the returned source-accept ... confirm-source command, commit-preview JSON and its exact Git command, then inspect ID and its reconcile ... confirm-inspection command when partial. All surfaces use this SDK authority. See the retry/checkpoint contract (not public yet).

Owned Local and Remote user consoles

terminal.open(sessionId) is an explicit user action, not an agent tool. terminal.defaultRoot() discloses the canonical home directory without starting a process. terminal.openGlobal(root) explicitly opens one profile-owned Local console with actual null session/project fields. It does not create a fake chat, inherit a repository or grant workspace access to a model. Concurrent opens reuse the same exact live root/intent rather than creating another global PTY. terminal.open(sessionId, cols, rows, undefined, root) supports a project-free Local user console only when that root is explicitly supplied. A project-bound console still uses the exact selected project/worktree, never an alternate root.

terminal.read(id, offset, limit) returns the exact Local or Remote binding, actual attachment generation, bounded volatile data and base/next offsets. A missing prefix or expired buffer is not reconstructed as a transcript.

const opened = await sdk.terminal.open(sessionId);
if (!opened.id) throw new Error("No terminal was admitted.");
const page = await sdk.terminal.read(opened.id);
console.log(page.terminal.status, page.terminal.binding?.root);
await sdk.terminal.reconcile(opened.id); // Inspect, never launch or resend.

terminal.input(id, text, signal?) splits bounded input without splitting a surrogate pair, and checks cancellation/current attachmentId between chunks. An error can mean some bytes arrived: inspect before typing again, never retry the same input automatically. Neither input nor resize uses durable command receipts. Reconciliation and input require the original profile/root identity; policy can block new input in either captured env without preventing inspection or exact close. Remote metadata never becomes a Local filesystem path or PID.

For Remote, explicitly configure/probe the installed worker and mapped project before a new terminal.open. Probe metadata separates optional console helper availability from core-agent readiness. The technical owner key is independent of provider/MCP credentials. The actual SSH host chooses the default shell; controller-side shell preferences are not substituted. No model is required. TerminalOwner.env === "Remote" and owner.remote expose the immutable peer/ helper boundary; preparing can retain null paths/PID before remote resources. Consumers must handle that state, not cast it to a prepared Local owner. Existing recovered Remote input needs its current allowed peer/root and authenticated attachment, not another core-agent probe. See the Remote lifecycle contract (not public yet).

terminal.reconcileOwner(ownerId) also inspects an empty pending owner. acknowledge(id, true) and acknowledgeOwner(ownerId, true) require actual user process inspection and do not prove historical cleanup or delete an unverified capability. Owner acknowledgement cannot hide unconfirmed terminals.

stopMoguriService(stateDir, { preserveTerminals: true }) requests an authenticated service-wide restart detach; ordinary stop/default embedded runtime.close() closes known groups across its loaded/recovered profiles. An explicit embedded runtime.close({ preserveTerminals: true }) also preserves them. Failed private cleanup keeps the registry and writer lock, blocks new work and permits an explicit cleanup retry. No saved PID is blindly signalled. See Local ownership, secret backend and cancellation (not public yet).

Smart compaction and /compact

Automatic compaction is on by default. Read or change it through settings.values.compaction (absent means defaultCompactionSettings()); automaticCompactionPolicy(values, isKupo) and compactionTrigger(policy, window) from the SDK root describe the exact policy the service applies. Reset it with sdk.settings.reset("compaction", revision).

// /compact: one explicit metered summary, applied only if complete and smaller.
const { id, preview } = await sdk.compactions.compact(sessionId);
// Kupo chats name a real model: sdk.compactions.compact(sessionId, { modelId })

Automatic and /compact entries carry their origin: automatic.actor is default-policy or user-policy (with automatic.scope: "session-model" for fixed-model chats), and /compact entries set applyOnSuccess: true.

Built-in slash precedence

builtinSlashClash(name) returns the built-in command (shared or TUI-local) that a skill name collides with, and builtinClashNotice(skill, builtin) the user-facing rename notice. Gateway skills carry shadowedBy, the catalog from sdk.commands.list(sessionId) returns such skills as kind: "shadowed" entries that clients must not select, and capabilities.importSkill returns a notice when the imported name clashes.

Optional Stainless browser

Protocol 111 adds sdk.stainless.status(), check() and open(sessionId, url), plus executeStainlessCommand(sdk, "status|check|open [URL]", sessionId?, fallbackUrl?) shared by /stainless and moguri stainless. Status reports enabled, availability (missing/invalid/found), the detected installation, whether the build is tested, the last in-memory check and automation (off/unavailable/needs_check/incompatible/ready). The playwright tool accepts launch: { kind: "stainless", url } and a diagnostics action. See the Stainless contract (not public yet).

Reviewed context compaction

sdk.compactions.state(sessionId) returns actual retained history, active ID, current source digest and labeled active/original conversation estimates. Preview is free of inference:

const { preview } = await sdk.compactions.preview(sessionId, {
  keepRecentTurns: 2,
  modelId: actualAvailableModelId,
});
const requested = await sdk.compactions.generate(sessionId, preview, true);
// Inspect state after actual settlement, then read the exact proposal.
const { compaction, text } = await sdk.compactions.read(sessionId, requested.id!);
// Only after the actual user reviewed text and compaction.status is proposed:
await sdk.compactions.apply(sessionId, compaction.id, compaction.revision);

Generation owns one read-only control turn, not a fake user prompt or optional subagent. It uses an actual selected model, at most 1,024 output tokens (or its stricter model/budget bound), normal cancellation and all-role admission. sdk.compactions.stop(sessionId, compactionId) targets only that exact running operation; a stale request cannot stop newer solver work. Synthetic kupo requires an explicit real compactor. Missing usage stays held; tools, incomplete/expanding output and changed source/model/policy cannot be applied. Text-only support rejects image history without dropping it.

Original encrypted history, complete recent turns and drafts remain retained. The synthetic context-only summary has no usage anchor; it never replaces the actual compactor report or ledger charges. Read/discard/restoration do not make paid calls. Restore with the current state's activeId and sourceDigest: sdk.compactions.restore(sessionId, activeId, sourceDigest, true). Restoring may exceed the working window; normal admission still fails closed. See the compaction contract (not public yet).

Explicit provider-declared metadata

(await sdk.models.evidence(actualModelId)).evidence returns a ModelEvidenceReport for one currently available concrete Copilot API ID. It copies only explicit capabilities.family, optional vendor/version, exact provider/model/source field, observation time, digest and the limitations. status:"unknown" and null claims mean the provider did not declare a family; no name prefix, model alias or local endpoint is treated as lineage.

CLI moguri models evidence MODEL_ID, shared/native TUI /model-evidence [MODEL_ID] and desktop Model / Provider-declared model metadata / Read Copilot model declarations use this same read. Omitting the slash argument requires the current fixed model; unset/kupo selection is an explicit error. This never selects/configures a model or changes the draft.

The service uses current profile-scoped short-lived request access and an exact HTTPS Copilot API root, with no redirect, alternate URL or ambient credential. Reads are bounded to four concurrent requests, ten seconds, 256 KiB and 512 distinct model IDs. Invalid fields, credential echoes, stale account/model bindings, logout and cancellation cannot return a successful old report. Remote sessions disclose that this metadata read is on the local control plane, not evidence about a different SSH account's model implementation.

Reports are not signed attestations, independent-family proof, cost/quality measurements, user answers or permission. They add no model call, durable evidence event, automatic cache, pool widening, compound mode or Max. Ordinary Copilot login/discovery/inference is unchanged. See the exact source/digest and qualification contract (not public yet).

Automatic Kupo

sdk.routing.policy() defaults to workflow: "auto", enabled, with no explicit classifier and an empty approved-ID list meaning all eligible configured models. Selecting KUPO_MODEL_ID is still an explicit session action; saving/resetting policy never starts inference or grants tool permissions. Existing explicit Single/Compound policies survive upgrade.

sdk.routing.capabilities(env?) returns the service-owned declared capability inventory without inference or extra provider inspection. General, reasoning, tools, vision and long-context categories describe declared support, not calibrated quality or billing; absent tool support is null. An optional env filter does not change the service's dispatch authority.

The shared catalogue always includes Kupo, even with no eligible environment. Zero eligible models blocks admission. One uses that model directly with no classifier step; its retained plan has basis: "only-model" and null confidence. With multiple models the bounded router selects an exact Single, Cascade or eligible Critique binding based on the task and inventory. Critique needs a current exact-model reviewed lineage claim; provider names cannot create it.

Each response proposal and read-only review is recorded with actual role/model usage. routing.response_selected points to the exact original result before the normal worker may process its tools. Rejected responses never become ordinary context or artifact sources. Selected responses preserve their actual model actor in conversation, activity and artifact promotion, including after restart. Manual approvals remain separate. Unknown usage, stale state, output limits, failed receipts and cancellation halt continuation without paid replay.

Finite automatic budgets, images, synthetic tuning and Sandbox remain blocked. See the automatic response contract (not public yet).

Explicit Single routing

Use defaultSingleKupoSettings() to construct a disabled explicit Single policy. Configure exact discovered model IDs with sdk.routing.configure(policy, observedSettingsRevision); the policy has workflow: "single", an actual classifierModelId, explicit approvedModelIds, separate allowHosted data consent and a minimumConfidence threshold. ModelInfo.endpointBoundary is derived from validated configured URLs; network/unknown destinations require consent even when their provider is named local. Loopback is the execution host's HTTP boundary, not proof against forwarding by a configured proxy. Configured-model inference rejects redirects. Copilot metadata retains the maintained model's actual output bound rather than a fixture-only or invented value. This is uncalibrated model advice, never an actual user answer or permission.

Only after saving, explicitly select modelId: KUPO_MODEL_ID through normal session controls, the picker or /model kupo. /kupo status, /kupo set POLICY_JSON and /kupo history use the same shared dispatcher. The session stays labeled kupo; snapshot.routings, session.usage and budgetEntries retain actual roles/models, plans, outcomes and charges. Classifier output never enters solver context. Invalid, stale, unreported or over-limit classifier results pause without fallback or another paid attempt.

This policy uses the same Local/pinned-SSH worker and exact approvals. Finite Local admission needs its separately qualified reserved wind-down policy; images and per-model tuning remain unavailable. Restoring settings.reset("kupo", revision) returns to automatic routing without deleting retained accounting or provenance or starting inference. See the durable routing contract (not public yet).

In Guided mode ask_user may include a bounded offered-choice recommendation. UserQuestion.recommendation contains the exact choice/reason and service-stamped model actor/model/provider/step/call provenance. It is not question.answer. Only an actual questions.answer/answerDraft user action resolves the wait, and the user can select a different choice. Approval recommendations similarly require exact-step recommendationSource; no old narration is substituted. Advice comes from the original metered solver response, not another model request. Retained documents label model advice separately from the user's answer. No public command can supply a forged answer actor.

sessions.create(projectId?, title?, overrides?) resolves explicit controls over project.values.defaults, settings.startup.profile, settings.startup.global and factory values. session.defaults records sources and observed revisions. Existing sessions do not inherit later changes. These preferences do not weaken policy. Global preferences are intentionally shared; profile/project/session values remain isolated.

Protocol/database 55 adds a last-selected fallback when no model default is explicitly set. In Settings / Startup defaults, Global default model chooses a fixed model/effort shared across profiles, the last explicitly selected model/effort within each profile, or no selected model. Omitted modelId permits the remembered fallback; modelId: null explicitly prevents it. Higher-priority profile/project/session model settings still win, and existing chats are not rewritten.

sessions.selectModel(sessionId, modelId, revision?) records an explicit choice and clears the old working-window override. Since protocol 77 it preserves the thinking preference, uses an exact/next-higher supported effort or the highest supported effort if none is higher, and never changes the requested model. Optional controls.preferredThinkingEffort retains the original effort only when it differs from the actual modelOptions.thinkingEffort; switching back to a supporting model restores it. Kupo and provider-controlled models keep that informational preference without receiving a fixed-model override. sessions.modelOptions records actual effort changes; its optional fourth true also marks an explicit same-value effort selection and replaces any retained preference. An explicit default or /model-settings reset clears it. sessions.configure normally remembers model/effort deltas; its fourth false performs configuration without recording a new selection. Raw session.configure commands opt in with rememberModelSelection: true. Window-only/autonomy/env changes, session creation and model/role calls do not become selections. Resetting tuning on a session with no selected model also preserves the remembered choice; sessions.selectModel(sessionId, null) explicitly clears it.

snapshot.lastModelSelection contains the profile's model/effort pair and its optional retained effort preference, never a provider payload. The independent profile event survives source-session/project deletion and restart. Startup provenance labels the fallback last-used. Working-window settings are not copied from the source session; explicit model-option defaults remain authoritative. An unavailable saved model/effort stays visible and fails normal admission rather than substituting a provider or dropping context.

Immutable profiles

const created = await sdk.profiles.create("Work", "#557799");
const profile = await sdk.profiles.wait(created.id!);
const work = await sdk.profiles.open(profile.id);
try {
  const chat = await work.sessions.create();
  console.log(work.profileId, chat.id);
} finally {
  work.disconnect();
}

The original sdk and every existing DraftEditor keep their original destination. profileId is also non-writable at runtime. Clients switching scope must flush old draft editors, preserve/block unsaved local forms and owned dictation, then explicitly dispose the old client. Switching does not stop service-owned work or move model context, artifacts, accounts or approval authority.

connectMoguri({profileId}) selects an explicit scope; omission means actual Default. HTTP uses X-Moguri-Profile; WebSocket authentication carries the same immutable identity. Unknown/unready profiles fail explicitly, never fall back. The CLI/TUI accept --profile ID, overriding the explicit MOGURI_PROFILE_ID launch environment. One-shot CLI commands do not mutate another client's active selection.

Global environment policy and configured global caps remain authoritative across profile switching, source deletion and restart. profiles.defaults(values, revision) and profiles.globalBudget(limitOrNull, revision, true) use root revisions from profiles.list(). Profile settings.reset preserves shared global preferences and hard policies. Restore global preferences explicitly with an empty profiles.defaults({}, revision) action. Global accounting invalidation contains an opaque sequence, never foreign ledger rows or prompt content. See the profile contract (not public yet).

Writable Remote turns serialize by captured pinned SSH peer plus canonical workspace, including across profiles with different Local mappings. A foreign failed-root quarantine survives unloaded-profile restart until the actual owner explicitly resumes after inspection. Distinct SSH roots remain independent; pending read-only changes are not acknowledged lease release.

settings.localModels contains explicit endpoint IDs/names/URLs/auth methods and declared model limits. Metadata discovery lists only configured advertised IDs. Use models.setToken/clearToken for bearer credentials; no token belongs in settings. provider.connections keeps Copilot and local status independent; each model/call has actual provider/API-model provenance.

models.catalogue() returns the actual profile's provider list plus one model group per exact upstream apiModelId. It includes disabled and configured-but- unready offerings; snapshot.provider.models is the authoritative selectable set, plus the synthetic Kupo entry with its actual readiness. models.setProviderEnabled(providerId, enabled, expectedRevision?), models.setEnabled(apiModelId, enabled, expectedRevision?), and models.selectSource(apiModelId, concreteModelId, expectedRevision?) use the current profile settings revision when omitted. Concurrent edits fail rather than overwrite another client.

Multiple offerings require one explicit selected source. Disabled models, providers and unselected offerings fail raw session selection and every new model admission, not only /model. Disabling preserves credentials, source choices, current session/default IDs, original results and ledger charges. Reenabling Copilot explicitly refreshes its configured metadata; a refresh failure reports that the preference was saved without claiming connection or inference. Local/SSH changes reuse their exact configured endpoint flags. settings.modelPreferences and protocol-70 migration metadata persist this contract without rewriting old history. See provider/model availability (not public yet).

settings.remote holds a non-secret explicit SSH target, pinned public host key, selected local identity path, private remote state directory, installed worker argv, scoped-Copilot grant and remote-local endpoints. Projects separately set remotePath. remote.probe() verifies the actual worker digest/runtime; remote.status() reports current qualification. Model IDs carry their eligible environments. sessions.env() preserves an eligible selection and clears an incompatible model/options, never substitutes another provider.

snapshot.executions records owned run/target/root, cancellation, cursor and actual/unconfirmed cleanup. remote.reconcile(id) reads existing receipts and late accounting without replay. remote.acknowledge(id, true) records actual user inspection, not proof of cleanup. Remote endpoint keys use remote.setToken/clearToken, distinct from host-local keys. The installed moguri worker --stdio entrypoint exposes the versioned SSH bridge; it never starts a second local service. See the transport contract (not public yet) for still-unqualified side-panel/extension capabilities.

workspaces.files(sessionId, path), workspaces.file(sessionId, path), workspaces.git(sessionId) and plans.read(sessionId) resolve Remote sessions through that pinned SSH worker and the project's explicit remotePath, not through any Local path. Protected/denied paths, file bounds and Git filter/hook suppression apply on the execution host. Target, root, env or policy changes invalidate pending results; disconnects are errors, not empty views or fallback. These are explicit user views, not implicit attachments or model context. Remote /plan returns text in CLI/TUI, never a Local file-opener action. Remote plan writes use the same owned worker without a model request. Pass the exact reviewed binding as the fourth argument:

const plan = await sdk.plans.read(sessionId);
const saved = await sdk.plans.save(sessionId, editedText, plan.digest, plan.bindingDigest);
const retained = await sdk.artifacts.read(saved.id!);

plans.saves(sessionId), saveInfo(sessionId, saveId) and stopSave(sessionId, saveId) inspect/control actual operations. A thrown partial error can mean bytes already changed; inspect before a new explicit save. A repeated original command never replays its recorded intent after restart. Local callers retain the three-argument form. See Remote plan saves (not public yet).

attachments.file/image capture selected content. folderPreview, githubPreview and sessionPreview return exact source/size/exclusion/digest data; the matching folder/github/session method needs the reviewed digest and literal user confirmation. attachments.read checks the destination session's grant before returning text or private image bytes. Source changes require new preview; source-session deletion does not erase an independently approved destination snapshot.

Use sdk.command for project/session creation, draft/queue changes, controls, human approvals, archive/resume and allowed-env policy. These are the same validated commands used by both clients.

Project-free chats and reviewed configuration

sessions.create() or sessions.create(null) creates a real project-free chat. Raw session.create also permits an omitted/null projectId. Protocol 72 captures Session.homeRoot (canonical path/device/inode) for ordinary Local chats, matching their private console default without creating a project. sessions.home(sessionId, expectedRevision?) explicitly binds a legacy chat once; the SDK prepares legacy Home on explicit file/catalogue/MCP use. Reopening, changing defaults or navigating never moves the binding. Files and commands use existing scoped executors and approval policy, not another checkout or a state-directory fallback. Private role owners and non-Local transports do not adopt controller Home.

workspaces.home(sessionId) reads the captured binding and current independently retained writers; Snapshot.chatWriters retains original profile/session/turn, root, revision, background jobs and actual active/settled/unconfirmed/acknowledged states. workspaces.acknowledgeHomeWriter(sessionId, writerId, expectedRevision, true) is an actual-user inspection action for that exact original Home. Acknowledgement is risk acceptance, not process cleanup, a tool grant or queue resumption. Unknown ownership survives source deletion and unloaded-profile recovery. Model-only chats stay parallel; actual overlapping writes serialize.

workspaces.files/file, tools.catalog/execute, agentTerminals.list/read and shared /home work across SDK/CLI/TUI/desktop. Commands start fresh PTYs in Home, never private User-console state. Browser control still needs its actual attached native host/user toggle and normal exact tool approval. Explicitly targeted gh --repo owner/repo or git -C /selected/checkout commands can perform repository work; native project pickers/publication, repository memory and project-file capture still require real project ownership. No account/login or project association is inferred. Home-dependent MCP grants bind the new exact directory identity and require fresh review rather than reusing an older null-root resource grant. Explicit automatic approval remains separate from hard denials, read-only modes, allowed environments and budgets.

Protocol 105 adds chat repository binding (docs/architecture/chat-repository-binding.md). Session.repositoryProposal ({ root, turnId, observedAt, status: "pending" | "dismissed" }) records a Git repository nested below Home that this chat tree actually wrote into. The pure helper sessionRepositoryProposal(session, snapshot) returns { root, project, confirm } only for a pending proposal; project is the existing project at that exact path or null, and confirm is settings.values.interactions.confirmRepositoryImport !== false. sessions.importRepository(sessionId, path, true, expectedRevision?) imports the exact proposed root (reusing a matching project) and moves the chat tree atomically. sessions.dismissRepository(sessionId, expectedRevision?) records "not now"; the same root is not proposed again. sessions.bindProject(sessionId, projectId, expectedRevision?) explicitly moves a Home chat tree into any existing project. All three require a settled root chat without a parent. The service moves chats automatically when the project already exists, or when the profile saved interactions.confirmRepositoryImport: false.

const general = await sdk.sessions.create(null);
const { preview } = await sdk.suggestions.preview(general.id!);
// Present preview.scope, sources and digest. No inference has occurred.
// After explicit source consent and selection of a model:
const analysis = await sdk.suggestions.generate(general.id!, preview.digest, false, true);
const settingsChat = await sdk.metachat.create(null, general.id, "Discuss Moguri settings.");

Project-free previews exclude project chats by default. Passing allProjects: true requires an explicitly project-free source and matching reviewed digest; generation does not silently widen scope. Metachat can read non-secret config or create proposals through moguri_config, never apply, authenticate or grant permissions. Optional ordinary evolution still starts off.

configuration.propose(sessionId, spec) creates a user-authored proposal; model-created ones retain actor: model. Specs identify global, project, policy, repo-instructions or skill, section/value/reason and optional verified evidence IDs. configuration.review(id) returns the exact before/ after value and warning. Only after actual human review/risk acknowledgement, call configuration.decide(id, true, reviewed.proposal.contentDigest, true). Reject with false. Status, base revision/digest and target validity are rechecked at apply. Skills install disabled; repo writes are local and report partial effects if their durable decision fails. Proposals survive origin-session deletion in their independent target compartment.

attention.list({query?, type?, state?}) returns the actual profile's visible Inbox notifications using the shared filterInboxAttention selector. Queries are case-insensitive, NFKC-normalized, at most 200 characters and require every whitespace-separated term to match. Types include "question", "failed" and "script-review"; state is "all", "read" or "unread". Search resolves the notification's original public source, never an unrelated latest message. Filtering neither reads nor resolves items and desktop filter state resets across profiles. CLI: inbox list --filters JSON; TUI: /inbox list JSON. attention.acknowledge(ids) marks shared items read; it never answers/approves. attention.delete(ids) atomically removes the exact notifications from Inbox, not their sessions, questions, approvals or budgets. An inactive deletion witness prevents replay; session deletion removes its notifications and witnesses. Stale/foreign/deleted IDs fail without removing a valid prefix. Preferences are settings.values.notifications: inApp: true, os: false, previewContent: false by default. Native OS delivery/navigation is an Electron binding of service events, not a second notification state store.

Root application configuration is separate from profile settings: application.status() returns the current root configuration; application.configure({menuBar: false}, observedRevision) saves only that leaf. Competing profiles share one revision and do not copy native preferences into their own configuration.

Protocol 96 also exposes the default-on root preference configuration.values.keepServiceOnWindowClose. application.configure({keepServiceOnWindowClose: false}, observedRevision) opts out without changing other preferences. It governs desktop window close, not explicit Quit, tool permissions, held queues or model budgets. Legacy application flags retain their values through the genuine-95 migration.

Node ensureConnection and connectMoguri accept an optional confirmUpgrade(review) callback. Discovery validates private loopback metadata and authenticated health before classifying a responsive older service as ServiceProtocolMismatch, rather than calling every version mismatch corrupt. The review exposes only root/PID/protocol/fingerprint facts, not its connection token. A true result allows one exact fingerprint-rechecked authenticated terminal-preserving restart; a false result raises ServiceUpgradeCancelled without stopping anything. Newer/unverified owners are never offered as an automatic downgrade/restart. Without a callback, callers receive the actionable mismatch and may choose an explicit lifecycle operation themselves. autoStart: false stays strict and never invokes upgrade/launch effects.

restartMoguriService({stateDir, expectedConnection?, runtime?, servicePath?}) performs an explicit service-wide terminal-preserving restart and returns the new authenticated ready Connection. It captures one root for the whole operation and verifies the selected service entrypoint/executable before requesting shutdown. Missing/incomplete installations cannot first interrupt a healthy service. Omit runtime/path overrides to use this SDK's actual installed layout and current Node executable; no development checkout, different app or ambient Node is substituted. Ordinary stopMoguriService remains separate and does not launch a replacement.

Cold auto-start waits up to 60 seconds for matching authenticated health rather than timing out after ten seconds during encrypted-history recovery. A process that exits without another retained writer reports its exit code/signal and exact private log path promptly. Competing launch clients may still connect only to the verified owner; a writer-lock file alone is not authentication. A deadline leaves the original initializing owner and all state intact, with no automatic retry, force-stop or replacement. Health reporting stopping/unconfirmed lifecycle work is not accepted as ready. Lost lifecycle acknowledgement may mean the original owner is already stopping; it never authorizes another launch.

An unconfirmed readiness deadline now raises Node ServiceStartupUnconfirmed, whose .review getter returns an independent ServiceStartupReview copy. The original canonical root/device/inode, private writer-file fingerprint, PID and available connection fingerprint are captured before health inspection, not rediscovered as a new owner after failure. After an explicit user reconnect, ensureConnection({startupReview: review}) retries only that captured owner and still requires a matching protocol. It cannot launch a process, create another root or choose a different installation. reviewServiceStartup(stateDir) is read-only inspection; waitForStartupService(review, {signal?}) authenticates that original owner without the caller-version gate for explicit lifecycle handling. These helpers do not approve a restart. ensureConnection also accepts signal; cancellation ends this caller's wait without stopping the shared service or replaying work.

Profile-owned metadata-only OTLP export

Protocol 97 adds sdk.telemetry.export.status(), review({enabled, endpoint, samplingRatio}), and apply(originalReview). The Node service owns one bounded sender per enabled loaded profile. Root and React entrypoints expose only browser-safe DTOs/API calls; official OTLP codecs load lazily in the service, never in ordinary Node SDK discovery.

Review is offline and binds the actual immutable profile, configuration revision, collector origin and metadata disclosure. Apply requires that exact review; it does not select a model, grant tools or alter accounting. An absent configuration is disabled. OTEL environment configuration and raw content export are unsupported. Service-owned health counters do not become retained billing or backend-delivery receipts.

const reviewed = await sdk.telemetry.export.review({
  enabled: true, endpoint: "http://127.0.0.1:4318", samplingRatio: 1,
});
// Present the exact review and privacy disclosure to the actual user first.
await sdk.telemetry.export.apply(reviewed.review);
const health = await sdk.telemetry.export.status();

Protocol 112 adds optional logs and headers review input, and setCredential(endpoint, name, value) / removeCredential(endpoint, name). Credential values go only to the profile's secret backend, bound to that origin and header name; status reports headers: [{ name, stored }] and log counters, never values.

The shared executeOtlpCommand(sdk, argument) parser implements CLI/TUI status, review INPUT_JSON, apply REVIEW_JSON confirm-reviewed and credential remove ENDPOINT NAME. It refuses credential set, because values must come from a masked TUI input or piped CLI stdin, never a command line. The export contract (not public yet) defines privacy, traces, canonical gauge semantics, finite bounds and restart/no-backfill behavior.

sdk.analytics.overview() and sdk.analytics.session(sessionId) read the service's in-memory live session analytics (not public yet): lane events for running and recent sessions only. The service never persists or exports them, and returns null for a session that is gone, archived or quiet for longer than the window.

After accepting a same-connection, exact-profile HTTP snapshot, the client uses its validated sequence as the event resume cursor. It does not replay the full retained history from zero before authenticating. Events committed after that snapshot, including the HTTP-to-WebSocket gap, remain delivered. A late ready frame cannot roll back newer snapshot data or cursor progress. This avoids large-history replay/backpressure consuming the unchanged ten-second event negotiation window; it does not truncate service history or resend a mutation. ClientState.events is the bounded live delivery window, not retained history; use the authoritative snapshot/activity/source-result APIs for earlier state. If negotiation still fails, its error retains the observed event close diagnostic (authentication/protocol/profile or replay recovery), not arbitrary server-supplied frame contents.

CLI, TUI and desktop builds import the actual dist/sdk/node.mjs rather than inlining its location-sensitive runtime paths. Packed SDKs retain the same explicit dist/service.mjs/dist/runtime.mjs layout. Private connection/lock reads are bounded and inode-checked through no-follow handles. Stale-lock reclamation is serialized by a private service.lock.recovery claim; a retained unconfirmed claim is not deleted or replayed automatically.

Explicit native Quit, and window close with the background opt-out, call stopMoguriService(capturedStateDir, {expectedConnection: capturedConnection}), not a freshly inferred default root. The private registry fingerprint and authenticated PID/protocol must still match that captured owner before sending the existing ordinary-stop lifecycle request. A missing registry is considered already stopped only with no writer lock or recovery claim and a refused captured endpoint. Without a captured owner, stopping a never-started/already-stopped root is idempotent only when all three metadata paths are absent. A missing connection with a retained lock fails explicitly; it is not permission to signal a PID, delete state or start another writer. A rotated/new owner is never stopped implicitly. Those stop paths wait for completed shutdown, not merely request acceptance. With the default-on preference, accepted last-window close reads the actual root configuration, verifies the original owner and quits Electron while the service, agent work and user terminals continue. Unsaved-edit cancellation does not begin shutdown or latch a later window close into the cancelled Quit intent. Explicit terminal-preserving restart remains separate. An established desktop's reconnect after an explicit same-root/store restart authenticates the new current private connection without launch effects, preserving its immutable profile and original store identity. Startup timeout and cancelled-quit continuations keep their stricter captured-owner review. The current authenticated operational owner, not an obsolete pre-restart token, is used for a later ordinary Quit.

application.storage.status() and application.storage.preview(path) expose the actual runtime authority and exact review. After actual all-profile review, application.storage.relocate(path, review.digest, true, optionalOriginalId) uses transient authenticated intake, retains intent and closes every writer. It does not refresh/reconnect a profile after requesting that shutdown. Node consumers can use waitForStorageRelocation(actualLocatorDirectory, id, keyId); the directory comes from actual storage status, not a guessed Home path. readDefaultStateLocation, readStateLocation and stateLocationDirectory are explicit Node exports. Source receipts, master-key identity, independent retention grants, unknown budgets and original resource roots remain intact. No original move ID can redispatch a copy, even after a missing receipt. Embedded createRuntime consumers must explicitly configure storage authority to enable a first move. Once a store records that authority, later views cannot discard it or substitute another locator to open a stale copy.

application.disk.status() returns the optional virtual disk for new session worktrees (supported, the disk record with status and pressure, live usage and the number of worktrees on it). application.disk.configure(sizeGiB, expectedRevision) creates or resizes it; configure(null, expectedRevision) turns it off. Changes finish asynchronously: read status() until disk.status is ready or off. Resizing refuses running work on the disk and turning off refuses worktrees still on it. See virtual disk (not public yet).

application.updates.status(), history(), read(id), credential(), setToken(tokenOrNull), check(automatic?, optionalOriginalCommandId) and cancel(id) use root-owned update state and a purpose-specific secure PAT. Credential intake is transient; normal provider/CLI credentials are not read. No raw token enters durable commands, receipts, event diagnostics or model history. Inspection and staging do not execute downloaded code.

After actual human review, application.updates.installPreview(id) binds fresh old/new tree digests and the canonical owned packaged destination/backup. install(id, review.digest, actualDesktopPid, true) is a transient shutdown request, not a normal command followed by automatic reconnect. Its acknowledgement identifies one private journal and immutable intent digest. Node waitForUpdateInstallArm(journal, id, intentDigest) waits for the original durable shutdown/arm acknowledgement before the native owner exits. It never replaces a missing helper or retries filesystem effects. Root configuration, update and store-relocation intents remain separate from per-profile settings and session retention; a pending installation blocks store relocation. Source/embedded runtimes need explicit updates authority to check releases; production derives the packaged installation root from the actual pinned Node runtime, never a user-selected arbitrary application path.

needsInputSound and completedSound each default to {enabled: true, id: "default"}; soundWhileFocused defaults true. Saved explicit mute/focus choices remain unchanged. Attention audio covers actual unanswered questions, pending approvals and failed/partial work, never a heuristic badge. Sounds do not depend on the banner flag. notifications.importSound(name, pcmWav, optionalCommandId), notifications.list(), notifications.sound(id) and notifications.removeSound(id, observedContentDigest, true) use immutable, profile-owned encrypted snapshots. Imports require canonical mono 16-kHz PCM16 WAV up to ten seconds and at most 32 retained sounds. Removal rejects currently selected resources, even when the corresponding alert is disabled. An original import command cannot recreate removed audio after receipt loss. File loading is explicit Node client delivery through loadNotificationSoundFile(path); the browser-safe SDK never gains arbitrary filesystem authority. No TUI/CLI operation automatically plays audio.

Streaming desktop dictation uses voice.startCapture(sessionId, optionalOriginalId, { streaming: true }), ordered voice.appendCapture(sessionId, id, token, sequence, pcmBytes), voice.readCapture(sessionId, id, token) and voice.finishCapture(sessionId, id, token, finalSequence). The original intake acknowledges frames without waiting for model startup; read returns the current transcript/revision, and the final capability job retains the acknowledged complete transcript. Duplicate/out-of-order frames, late audio after revocation and incomplete flushes are rejected, never replayed. startCapture resolves with the exact service lease acknowledgement, without waiting for a full conversation snapshot. Observe its job through the shared event stream or jobs.wait; no second capture queue or admission retry is used. DraftEditor.startDictation(start, end) replaces only its original provisional span, preserving surrounding typing and refusing foreign/overlapping changes. An ordinary autosave does not delay this local span; pending input intake and attachment capture are refused rather than arming a later recording. Insertion never sends a prompt.

The retained batch API uses voice.startCapture(sessionId, optionalOriginalId), voice.uploadCapture(sessionId, id, token, wavBytes) and voice.cancelCapture(sessionId, id, token). These use transient authenticated /v1/voice requests, not durable commands. The original profile/session/job and one-use nonce stay bound through cancellation and disconnect. The maximum normalized clip is 120 seconds / 3,840,044 bytes; malformed rates/channels, noncanonical base64, duplicate upload and reused job identity are rejected. Audio and upload nonces are never retained in events/receipts. Actual ASR jobs and explicit transcript insertion still use existing shared APIs. Root exports encodeSpeechPcm, encodeSpeechWav, validateSpeechWav, shortcut parsing/matching helpers and typed preferences without importing native/provider runtime.

await sdk.voice.transcript(sessionId, jobId) returns the complete recognized text from a completed local speech job owned by that exact session/profile. It reads bounded result pages, including JSON escaping, without truncating them or opening a microphone. Pending/cancelled/foreign-session results are rejected. voice.insert(sessionId, jobId, expectedDraftRevision) remains a separate explicit write and never submits a prompt.

sessions.side(parentSessionId) atomically opens an existing original side chat or creates one with the parent's model, thinking/window, autonomy and budget, capturing its real effective context. It remains permanently read-only. Navigation attachment alone never grants another parent's context.

Held prompts, modes and retained plans

import { DraftEditor } from "moguri";

const session = sdk.getState().snapshot?.sessions.find((item) => item.id === sessionId);
if (!session) throw new Error("Choose a session.");
const editor = new DraftEditor(sdk, session.id, session.draft);
try {
  editor.edit("Review the generated change.");
  const held = await editor.send("queue", true); // No model call, even when idle.
  console.log(held.id);
  editor.edit("/read-only");
  await editor.submit((expectedDraftRevision) =>
    sdk.commands.submit(sessionId, { client: "cli", expectedDraftRevision }));
} finally {
  editor.dispose();
}
const side = await sdk.sessions.spawn(sessionId, "side");
const plan = await sdk.plans.read(sessionId);
// A read-only session cannot save a plan or promote a question-only child.
// Actual UI results require a compatible commands.attach handler and acknowledgement.

prompts.sendNow(sessionId, messageId) steers a queued prompt into the live solver turn, or runs it next when idle. prompts.edit(sessionId, messageId, text, attachments?) saves a queued prompt; pass the complete attachment list, using kept entries plus captures from attachments.queued.file|document|image| folder|github|session(sessionId, messageId, ...), which return { id, attachment } for the staged capture without touching the draft; attachments.queued.list(sessionId, messageId) lists what's staged. See queued prompt editing (not public yet).

Release a held prompt with prompts.release(sessionId, messageId, observedQueueRevision) only after explicit user admission. A selected available model, ready environment and policy are required then, not when holding text. /run ID uses this same operation. Returning to agent mode is a safe-boundary request; immediate restriction and model-declared tools are service-enforced.

DraftEditor.submit(intake) fences its original acknowledgement and buffers later input. Only canonical queued-command draft provenance may merge an owned delayed context capture; foreign draft edits still require explicit conflict resolution. Submission, context capture and clipboard success are not inferred from matching text. A lost acknowledgement never triggers a paid retry.

Ordinary DraftEditor.send exposes its captured local input through getState().pendingInput while the composer is cleared and the original request is awaiting acknowledgement. Desktop and TUI label it as Sending, Holding, Steer or Interrupt, never as a committed message or model start. It is not a durable event, model context, receipt or permission. Newer edits remain independent; refusal or unknown acknowledgement restores the existing draft/conflict recovery without automatically resending. Generic submit(intake) does not turn a question answer or slash action into a provisional ordinary message.

DraftEditor.send("auto") asks the service to choose ordinary Queue when idle or Steer at the actual active solver's next safe boundary. It does not cancel the current operation, answer a structured question or target a private control turn. Held auto input and slash commands remain ordered queue intake. Only a marked automatic live item can become the next turn if its owning solver finishes before consuming it; stop/partial recovery never performs that transfer.

sessions.create(projectId) records factory-title provenance. Supplying a title, including an old placeholder string, does not infer automatic naming. The optional profile setting is chatTitles: { enabled: true, modelId: null }; null means the qualified original-Env selection described in First-topic chat names (not public yet). Saving settings does not send inference. sessions.titles(id) reads actual optional Snapshot.chatTitles records, including original source/request/result digests and rejected/partial outcomes. The extra title role appears in shared all-role usage and budget filters, never ordinary solver context or model-owned acceptance.

sdk.getRequestTimings() returns copies of the last 50 settled SDK request observations: allowlisted operation, connection generation, HTTP status, headers/body/total milliseconds and whether delivery completed. These are client transport observations, not server CPU, inference, billing or readiness proof. They retain no input, identifier, path, endpoint, credential, model name or request/response payload and are not persisted. Desktop Insights and TUI /trace expose the same diagnostics without issuing new model requests. Current responses add optional numeric response spans: serviceMs, proxyBodyMs, proxyHeadersMs, and each process's LoopMs/WindowMs. Absent headers/samples are null, not zero. Loop maxima describe lag above nominal 20-ms sampling in the reported window; they are not correlated CPU, lock or network causes for that request. The copy retains no raw HTTP header.

commands.attach(client, handlers, {canApply?, onError?}) returns {clientId, wake, dispose}. Handlers receive the original SDK/session, execution, input/result, private claim and AbortSignal. They return an explicit completed, cancelled, failed or partial outcome after actual application. A set-state callback or printed unavailable action is not successful native UI delivery. commands.choose(clientId, claim, choice) atomically binds an actual original queued continuation choice and its admission; it never consumes a newer draft. Only cancelled, non-mutating continuation reviews may request restoreInput, and restoration requires an unchanged empty original composer. UI instances should await their attachment disposal, or commands.detachAll(), before closing their test/runtime resources. Service-capable commands do not depend on these clients remaining connected.

Project settings use projects.configuration and projects.configure(projectId, settings, observedRevision). projects.add(absolutePath) registers an existing canonical directory. projects.clone(repositoryUrl, newAbsolutePath, true) returns an independently retained project.clone capability job, not a completed project. Wait with jobs.wait(id) and inspect its actual status before using job.projectClone.projectId. Successful project registration and job.finished commit atomically. The intent retains canonical destination/parent identity, containing-root leases and original command ID/digest. Cancel, restart or a lost receipt never repeats the original Git operation or deletes partial files. Cloning does not run hooks/checkout filters/submodules, initiate personal login or start inference. Existing destinations and embedded URL credentials fail before effects.

projects.sources returns the actual instruction/MCP source and mcpDigest; projects.importMcp(projectId, observedRevision, true, reviewedDigest) rejects file changes after review and installs supported entries disabled. Project MCP auth/token operations must include their bound session ID. projects.initialize is an explicitly confirmed non-protected-branch push job, not an implicit effect of reading settings. Inspect its terminal result: partial or cancelled publication is not success.

Artifacts are independently encrypted in project/profile scope. plans.save/capture retain a plan snapshot with unknown file authorship; plans.artifact remains readable after session deletion. Source-session deletion requires confirmation and an observed session revision. Project removal refuses retained managed worktrees; remove them explicitly first. It requires a reviewed artifact choice before forgetting project content/derived indexes and project MCP credentials, never source files, external PRs or shared caches/models. Archived retention is opt-in settings.values.retention; retention.run honors that policy. Production retention uses the explicit OS-keychain backend; generated embedders/tests may inject a 32-byte retentionKey, never hardcode a real key or silently derive one from a path.

Independent artifacts

const created = await sdk.artifacts.create(null, {
  projectId, kind: "decision", name: "Generated decision", text: "Explicit text.",
});
await sdk.artifacts.update(created.id!, { text: "Explicit revised text." }, 0);
const old = await sdk.artifacts.read(created.id!, 0);
const revisions = await sdk.artifacts.history(created.id!, 0, 20);
const source = await sdk.artifacts.source(sessionId, "message", messageId);
const answer = await sdk.artifacts.promote(sessionId, {
  sourceKind: "message", sourceId: messageId, kind: "answer",
  name: "Reviewed answer", expectedDigest: source.preview.digest,
});
const exported = await sdk.artifacts.export(answer.id!);

create(sessionIdOrNull, document) uses that session's explicit scope, or the supplied project/profile scope with no invented conversation/filesystem root. Promotion copies the exact canonical completed user/model message or terminal tool result, preserving its real actor, source event, digest and outcome. Later edits set edited, never relabel model text as a user answer. Archive is update(id, {status: "archived"}, observedRevision); restore uses active. delete(id, observedRevision, true) forgets that artifact's grants and all revisions, not other copies or source files. Reads/history reject deleted IDs even when another artifact contains identical text.

projectPreview(projectId) binds the exact current set to a digest. projects.remove(projectId, true, observedRevision, choice) accepts {action: "retain"|"delete"|"export", expectedDigest, exportedDigest?}. Export requires the exact projectExport digest and explicit client saving before deletion; retain creates a new profile-owned revision. Concurrent edits invalidate the choice. The explicit Node entrypoint exports saveArtifactExport(absoluteNewPath, export): private atomic new-file delivery, digest verification and fsync, no overwrite or automatic app opening.

Text is bounded to 128 KiB UTF-8, history pages to 100 records, JSON exports to 8 MiB with no truncation.

Artifact create/update accepts nullable folderId and workItemId. Folders belong to this profile; a work item must belong to the artifact's project. These are versioned associations, not a filesystem path or model permission.

artifacts.materializePreview(projectId, {workspaceId?, commitBranch?}) returns the exact source-set/file/review digests, canonical root identity, destination, policy revision and optional new local branch/base. Explicit artifacts.materialize(projectId, reviewDigest, sameOptions) durably starts an owned job before effects. Wait with jobs.wait, inspect the typed artifacts.materialization(jobId) and request stop through jobs.cancel. A timeout is not cancellation. Partial/interrupted jobs preserve source grants and their original destination intent; restart never replays publication.

Copying writes one exact private history bundle under that selected Local root's artifacts/. Optional commit uses a temporary index and a new non-protected local branch, preserving checkout, index and unrelated edits, with no push/signing/hooks/filters. projects.remove may use {action:"materialize", expectedDigest:setDigest, materializationId:completedJobId}. The service rechecks real bytes and any requested local commit before forgetting source grants. Changed source/file/root/branch rejects deletion. Remote/Sandbox publication is unavailable, not mapped to Local.

Actual structured answers

snapshot.questions contains typed model clarifications and their real status/provenance; session.pendingQuestionId identifies an active owner. questions.answer(id, text, observedRevision) accepts only actual user input for that live question/turn. It cannot set an actor, approve tools or answer another turn. questions.answerDraft(id, observedRevision) consumes the exact saved owning-session text atomically; flush a DraftEditor first. Attached context is preserved and stale draft/question revisions reject the entire operation.

Question routing respects explicit tool denials but does not ask for redundant permission to ask a clarification. Worker cancellation stays non-blocking; stop/restart cancels pending questions without manufacturing an answer. settings.values.artifacts.retainAnswers defaults true as requested. Answer event, independent artifact with model-question/user-answer sources, draft clearing and command receipt commit together; failure rolls back all. Disabling retention preserves canonical source events until their session retention applies. Model/delegated-decision answers require their own future policy/call provenance, never this actual-user endpoint.

Estimated limits and independent accounting

Session controls accept {kind:"limited", basis:"estimate", tokens?, usd?} with at least one positive limit. A finite control without explicit estimate policy is rejected. budgets.status(sessionId) returns actual/held/incomplete totals, effective session/profile caps and unavailable-unit diagnostics. budgets.policy(limitOrNull, observedRevision, true) is a separate explicit profile-policy action; settings/default resets never lift it.

USD admission requires either a fresh model-specific settings.values.budgets.rates entry with canonical modelId, inputUsdPerMillion, outputUsdPerMillion, UTC effectiveAt date and source:"user-estimate", or explicit settings.values.budgets.useProviderRatesForLimits: true consent for fresh originating-provider references. providerEstimates defaults on; finite-limit consent defaults off. An existing stale manual override is not replaced. prices.catalog() exposes reference dates, canonical source/digest, model matches and unknown-price diagnostics. prices.refresh(providers?, revision?) returns an original pricing.refresh job. Wait/cancel through jobs; failed refresh preserves the prior catalog. Calls capture their historical provider-api-equivalent or user-estimate rate. Unknowns remain unpriced; providerReportedUsd and billedUsd remain separate/null.

Reference prices deliberately assume the named originating model's API cost through Copilot/resellers, not their invoices. Known cache subsets are priced once, long-context thresholds are explicit, and unspecified write TTL uses the maximum listed write rate. The manual conservative input override still covers every input category. No provider total is inflated by adding cache twice.

Reservation and model.started commit before the real worker is authorized. The actual reduced output limit reaches maintained pi-ai. Complete reports settle once; stop, lost frames and restart retain full unknown reservations. Authenticated late SSH receipts can improve accounting without replaying work or completing partial turns. Profile-owned entries survive session/project retention. Historical unknown bounds/prices block affected finite units.

budgets.dashboard({projectId?,folderId?,sessionId?,turnId?,providerId?,modelId?,role?,env?,range?,bucket?,offset?,limit?}) returns complete matching totals, UTC periods/captured price history and paged actual role/model groups. range is {kind:"days",days:7|30|60|90|365}, {kind:"year",year}, {kind:"custom",from:"YYYY-MM-DD",to:"YYYY-MM-DD"} (inclusive UTC dates), or {kind:"all"}/omitted. bucket is day, week (Monday), month or all. Unknown historical request times are disclosed and excluded from dated views, not treated as zero; All time includes them.

budgets.calls({...sameScopeFilters,offset?,limit?}) returns bounded retained current-accounting call pages, actual/owning turn, nullable categories, captured rate and observed stream metadata. New/late reports can reorder pages; do not sum pages to derive totals. Observed delivery rates exclude unqualified and non-generative observations and are not GPU benchmarks. Absent cache details or single-chunk timing stay unknown. Use the same filters via /dashboard JSON, /dashboard calls JSON or CLI budget dashboard|calls --filters JSON. Estimates, provider reports and bills are separate; no billed USD is invented. Input reservation is estimated and provider charges can lag or exceed it. A provider exceeding its forwarded output bound is partial/unqualified for finite retry. A blocked request creates a deterministic retained checkpoint, not a model answer or successful commit. Kupo wind-down and committed checkpoints remain separate scheduler/Git qualification.

Protocol 30 additionally exposes budgets.plans({sessionId?,projectId?,folderId?, turnId?,modelId?,providerId?,role?,env?,range?,status?,offset?,limit?}). Read-only held/consumed/released pages are distinct from actual calls: plannedHolds, plannedHeldTokens and plannedHeldUsd disclose reserved future capacity in status/dashboard totals. Use /dashboard plans JSON or CLI budget plans --filters JSON. Plans have no call-time repository attribution, so that query rejects repository filters rather than silently ignoring them. Only still-held plans release on the canonical owner's termination; consumed or unknown calls stay charged/held through source deletion/restart. Creation/transfer remain internal prerequisites, not a public finite kupo feature or client-side refund authority. See the contract (not public yet). The 0.24 internal planner can calculate a complete same-turn batch before one atomic append, so future roles cannot independently reserve overlapping capacity. This adds no client write API or finite kupo readiness; existing inspection still returns the individual version-1 plans.

Tool outcomes and retained size

telemetry.operations({...sameScopeFilters,family?,actor?,name?,serverId?,outcome?,offset?,limit?}) returns all matching totals/groups and a bounded attempt page. Families are tool and mcp; actual actors are model, external or unknown. MCP attempts are not added a second time as gateway/result jobs. The failure rate denominator is completed + failed; denial, pending/running, stopped, partial, unconfirmed and unknown outcomes have independent counts. No known results means a null rate, not zero-percent failure.

The allowlisted ledger retains no arguments, paths, commands, prompts, output or error text. Source deletion does not erase sanitized metadata. Startup can import only retained evidence; coverage explicitly discloses unavailable pre-upgrade deleted history. Missing start time or elapsed samples are unknown, not zero. A late result does not turn its owning partial session into success. Explicit user plan saves remain their own control-operation history.

telemetry.storage() returns current-profile sealed event-payload, encrypted blob-grant and encrypted key bytes/counts in one read transaction. One content digest can have multiple real encrypted grants. Physical/freed disk remain null, and key presence is not a decryption/integrity audit. Structural payload copies, metadata/receipts/tombstones, SQLite overhead/WAL, forgotten ciphertext, worktrees/repositories, caches, weights, memory indexes and terminal buffers are excluded. It accepts no date/project/model filters.

Use CLI telemetry operations --filters JSON, telemetry storage, or shared /dashboard operations JSON and /dashboard storage. F7 and desktop Dashboard expose the same SDK projections. See the exact contract and prerequisite measurements (not public yet).

Verified repository filters

repositories.preview(sessionId) reads the actual Local/worktree or pinned SSH origin without GitHub access. Review its root, lookupBoundary, repository, bindingDigest and observation revision. repositories.refresh(sessionId, bindingDigest, revision, true) starts one owned job; inspect jobs.wait(id) and repositories.state(sessionId). repositories.clear(sessionId, revision, true) affects future attribution, not historical names, metadata or charges.

Public metadata uses the control-plane API without credentials; Local gh-cli requires explicitly selected project access. Protocol 26 uses the selected SSH account for Remote gh-cli, never a Local account fallback. Review preview.remote host/port/login/key fingerprint/root/build and lookupBoundary: "remote-gh-cli" before explicit refresh. The retained observation keeps that proof across restart. Missing tools/accounts and unconfirmed cancellation fail visibly without another request. Copilot credentials are not reused. Exact 0.20 delivery identities are recorded in setup. No network lookup occurs at model admission: configured calls recheck their actual Git identity and capture previously verified metadata or remain unassigned.

Budget/call/tool queries accept repositoryId, organization and visibility:"public"|"private"|"internal"|"open-source". Each result discloses repositoryCoverage before those filters. open-source is only the documented public-plus-detected-OSI category; missing license evidence stays unknown. entry.repository is an immutable admission snapshot, not today's GitHub state. Never sum filtered pages to infer cumulative charges.

CLI repository and shared /repository review/refresh/state/clear/stop commands expose the same API; /dashboard JSON accepts the new filters. See repository attribution (not public yet) for exact scope, cancellation, privacy, licensing and recovery semantics.

Managed Local roots

const intent = await sdk.workspaces.create(projectId, "moguri/generated-work", {
  baseRef: "main",
  // Optional issueId and verified-format prUrl retain change-set association.
});
const workspace = await sdk.workspaces.wait(intent.id!);
const created = await sdk.sessions.create(
  projectId, "Generated isolated work", { env: "Local" }, workspace.id,
);
const files = await sdk.workspaces.files(created.id!);
const file = await sdk.workspaces.file(created.id!, files.entries[0]!);
const changes = await sdk.workspaces.git(created.id!);
const registered = await sdk.workspaces.discover(projectId);

snapshot.managedWorkspaces and changeSets are authoritative projections. sessions.create accepts an optional fourth workspace ID; sessions.fromWork accepts an optional third ID. A fresh idle session may explicitly bind/unbind with workspaces.bind(sessionId, workspaceIdOrNull, observedRevision?). No mapping from a Local checkout to a Remote/Sandbox path is inferred.

Worker tools, repository instructions, plans, terminals, context, MCP cwd, cache installs and memory use the same root. Pass the optional workspace ID to memory.index/search/graph and cache.inspect/install when operating outside a session facade. Ordinary base-project callers retain their existing behavior. Deletion never removes a worktree or branch. Archiving removes only a clean, fully pushed worktree and its local branch when retention.archiveBranchCleanup isn't false, recording parked so restoring recreates it (D46 (not public yet)). Explicit removal requires a clean, idle, unbound owned root and remove(id, observedRevision, true). Wait observes its job; aborting a wait is not cancelling the job. Use jobs.cancel(workspace.jobId) for cancellation, then inspect partial outcomes. reconcile verifies existing identity/absence without re-executing Git. Discovery reports Git registrations, not new ownership or filesystem authority. External worktree adoption and multi-candidate orchestration remain unavailable.

Local reviewed repository candidates

Use an explicitly Local agent-mode source session with an explicit Git-backed project and a separate clean owned worktree at the same HEAD. Creating/selecting that worktree is a separate user action. Optional indexing, models and inference are not needed. candidates.eligibility(sessionId) exposes the service's current eligibility and diagnostic without creating a job, artifact or model call. It never borrows a previous project. Direct manual/generated/compound commands enforce this too.

import type { CandidatePatch } from "moguri";

const base = await sdk.workspaces.file(sourceSessionId, "src/example.ts");
const patch: CandidatePatch = {
  kind: "patch", summary: "Explicit reviewed edit",
  edits: [{ path: base.path, baseDigest: base.digest, text: replacementText }],
};
const preview = (await sdk.candidates.preview(sourceSessionId, stageWorkspaceId, patch)).preview;
const created = await sdk.candidates.stage(sourceSessionId, stageWorkspaceId, patch, preview.digest);
const staged = await sdk.candidates.wait(created.id!);
if (staged.candidate.status !== "staged") throw new Error("Inspect the actual retained outcome.");
const review = (await sdk.candidates.applyPreview(created.id!, sourceSessionId)).preview;
await sdk.candidates.apply(created.id!, sourceSessionId, staged.candidate.revision, review.digest);
const result = await sdk.candidates.wait(created.id!);

read(id) exposes the immutable document, exact roots, real stage/apply jobs and observed/attempted paths while its session-owned proposal remains retained. wait returns actual settled metadata, not a success-shaped retry. Inspect candidate.status and the original job; stop through candidates.stop(id). A wait timeout or client abort does not cancel work. A partial result never rolls back or retries newer user files; explicit existing root recovery is still required.

Permanent origin-session deletion, including archived-session expiry, deletes the candidate and its proposal/job/blob grants. Archiving alone preserves it. Fresh authoritative metadata for its exact first associated repository/PR can also delete it after a verified merge, including for archived sessions. Current metadata-access policy applies; no stale observation, closed PR or later session relink can authorize another candidate's deletion. Pending/failed cleanup is in snapshot.candidateCleanups; owner/PR bindings are in candidateOwners. Ordinary artifacts, shared grants, actual/unknown accounting and Git/filesystem resources are not erased or reverted. See the retention contract (not public yet).

New files use baseDigest: "absent" and need existing allowed parent directories. The slice accepts at most 20 portable distinct paths, 32-KiB patch JSON and a 64-KiB document. It does not create directories, delete/rename files, change modes or run code-quality validators. Byte/base checks and critic advice are not user acceptance or a project-test result. No commit/push occurs.

CLI: moguri candidate preview PATCH.json --session SOURCE --workspace STAGE, then stage PATCH.json with the same selectors, --digest and --confirm-write. Use apply-preview ID --session SOURCE, then apply ID with --session, observed --revision, fresh --digest and --confirm-write. read, wait, stop and explicitly reviewed reject expose the same SDK data. Shared /candidate JSON commands and the desktop Candidates panel perform the same two separate reviews. Source Env/mode/policy changes invalidate stale results; no Remote/Sandbox-to-Local fallback.

Reviewed peer/native staging resources

The protocol-92 Env contract (not public yet) preserves Local v1 behavior and adds explicit independent resources for selected Remote and Sandbox sources. Remote creates a detached Git worktree on the actual pinned peer. Sandbox creates a bounded copy of its original private snapshot, not a Git checkout or the live Local repository. Native physical admission remains unqualified while the documented pinned SendBox DNS issue blocks the factory workload. No fallback or automatic upstream repair is attempted.

const reviewed = (await sdk.candidates.workspacePreview(sessionId, "Reviewed draft")).preview;
// Display reviewed.source, stageParent, diagnostic and digest to the actual user.
const created = await sdk.candidates.createWorkspace(sessionId, reviewed.name, reviewed.digest, true);
const workspace = await sdk.candidates.waitWorkspace(created.id!);
if (workspace.status !== "ready") throw new Error(workspace.diagnostic ?? "Inspect original creation.");
const original = await sdk.candidates.source(sessionId, ["src/example.ts"]);
// Build a bounded patch using only these original path/baseDigest values.
// Existing preview/stage/apply APIs still require their separate exact reviews.

workspaces(sessionId) lists compatible original resources. workspace(id) reads independent retained metadata, including the planned path when creation is partial; stopWorkspace(id) targets only its original creation. waitWorkspace does not replay or delete resources and never implies success. Unknown worker cleanup blocks deletion of original ownership and proposal grants. Read-only source query receipts are scoped to their exact originating session, not another project/profile-level blob store.

CLI uses candidate workspace-preview NAME --session ID, then workspace-create NAME --session ID --digest SHA --confirm-write. candidate source PATH... --session ID, workspaces --session ID, workspace-read ID and workspace-stop ID inspect the exact selected Env. Shared native TUI commands use /candidate workspace-preview {"name":"Draft"}, workspace-create {"name":"Draft","expectedDigest":"SHA"} confirm-create, source PATH, workspaces, workspace-read ID and workspace-stop ID. Desktop displays the same root/base/build semantics and readiness errors. Native private application never supplies the separate native-to-Local publication/checkpoint acceptance.

For an interrupted standalone transport, candidates.transports({sessionId?, ownerId?}) lists up to 100 retained records, transport(id) reads its exact metadata, and reconcileTransport(id, expectedRevision) performs bounded read-only inspection against its original account/root/build/keyed journal. Reconciliation accepts no force/risk-ack option and never replays files, Git, VMs, scripts or models. Exact recovered receipts may confirm cleanup and retain the original result, but the operation/candidate/job/resource stays partial; original controller ACK and peer ACK evidence remain distinct. Missing or unverifiable receipts stay quarantined. No unknown charge is refunded.

CLI uses candidate transport-reconcile ID --revision N; shared TUI slash uses /candidate transport-reconcile ID N, with transports and transport-read ID for original metadata. Desktop exposes the same read-only receipt action. Attached compound-parent operations are not standalone recovery targets, and physical native recovery is still gated by the documented SendBox dependency.

Owned fixed-model proposal generation

Protocol 31 additionally supports one bounded, tool-less Local draft from original selected source files, not unsaved client edits. Select an available fixed model in the source session first. The stage remains an explicitly created clean managed worktree at the same HEAD.

const file = await sdk.workspaces.file(sourceSessionId, "src/example.ts");
const input = { task: "Describe the requested change", files: [{ path: file.path, baseDigest: file.digest }] };
const preview = (await sdk.candidates.generatePreview(sourceSessionId, stageWorkspaceId, input)).preview;
// The user reviews source/model/cost and session-owned proposal retention.
const started = await sdk.candidates.generate(sourceSessionId, stageWorkspaceId, input, preview.digest, true);
const generated = await sdk.candidates.waitGeneration(started.id!);
if (generated.generation.status !== "proposed" || !generated.proposal) throw new Error("Inspect the retained partial/stopped/failed outcome.");
const staging = (await sdk.candidates.preview(sourceSessionId, stageWorkspaceId, generated.proposal.patch)).preview;
const staged = await sdk.candidates.stage(sourceSessionId, stageWorkspaceId, generated.proposal.patch, staging.digest, generated.generation.id);

Application is still the separate review/application shown above. Inspect generation(id) and stop the owned call with stopGeneration(id). Wait abort/timeout never cancels inference. Missing usage remains held and raw invalid/stale output/actual charges remain inspectable. No retries or model fallbacks. A changed patch cannot retain the generationId assertion.

The report has separate encrypted grants for original input, raw output and canonical model provenance, but its lifecycle is owned by its originating session and exact first PR association as described above. New candidate and generation exports use version 10 with exact ownership/PR events; ordinary and historical exports keep their prior formats. Bytes are immutable; metadata edits remain available. Deleting the report prevents its original command from calling a model again, even without its old receipt. These retained data are not automatically promoted to solver context.

CLI: candidate generate-preview INPUT.json --session SOURCE --workspace STAGE, then generate INPUT.json with the same selectors, --digest and --confirm-cost. generated|generation-wait|generation-stop ID inspect the same record. Stage accepts --generation ID only for unchanged verified model output. SIGINT stops the exact generation and exits unsuccessfully for a non-proposed outcome.

Shared examples:

/candidate generate-preview {"stageWorkspaceId":"STAGE","input":{"task":"Requested change","files":[{"path":"src/example.ts","baseDigest":"FILE_SHA"}]}}
/candidate generate {"stageWorkspaceId":"STAGE","input":{"task":"Requested change","files":[{"path":"src/example.ts","baseDigest":"FILE_SHA"}]},"expectedDigest":"REVIEW_SHA"} confirm-cost
/candidate generation GENERATION_ID
/candidate generation-stop GENERATION_ID

Use actual IDs/digests. Desktop Candidates exposes source/model review, independent-retention/cost confirmation, actual usage/stop and local proposal loading before the two file reviews. TUI uses the same commands and metadata-only artifact editor. Limits and actual recovery/migration semantics are in the generation contract (not public yet). No compound kupo, quality calibration, Remote generation or Sandbox is enabled.

Model context and thinking

sessions.modelOptions(sessionId, options, observedRevision?) stores optional contextWindow and thinkingEffort alongside the session controls. Without provider-declared discrete restrictions, the working window accepts exact integer token ceilings from 8,192 through the selected model's fixed maximum. An actual supportedContextWindows list remains an exact allowed set. supportsModelContextWindow(model, tokens) is the shared browser-safe validator; modelContextWindows(model).values gives menu presets or the actual declared set, not an exhaustive list for unrestricted models. The window is enforced against the maintained library's labeled context estimate and output/headroom sizing, not represented as exact tokenization or a finite spend cap. Oversized estimates stop before inference without silently dropping or compacting history.

Use the selected provider.models[].thinkingLevels, not a hardcoded effort list. A transport may have reasoning but not expose configurable effort; unsupported options fail explicitly. Omitting effort uses the model default. supportedThinkingEffort(preferred, supported) and selectModelControls(controls, model) are shared browser-safe selection helpers. Fallback applies to an explicit model switch, not an unsupported same-model effort request or permission to substitute a provider. The control plane revalidates the resulting actual option before persistence/admission. Disabling a selected model/provider atomically clears affected session selections through existing session.configured events. Re-enable does not reselect; drafts, held queues, actual admitted accounting and retained effort remain independent. Registry availability and the shared routingModelReady/routingWorkingWindow capability checks keep unavailable models out of actual Kupo admissions. Protocol 77 requires the explicit model_selection_continuity_schema = '1' store marker; missing/corrupt or prematurely retained provenance is not repaired from a numeric version. Standalone 77 still refuses future state. A separate themes marker is not evidence that the model migration ran. sessions.context(sessionId) reads an estimate including saved draft, instructions, tools and conversation without calling a model. The normalized provider payload stays service-side.

Desktop puts these settings in the model-name popover. TUI uses /model-settings to inspect, /model-settings JSON to apply and /model-settings reset to restore defaults. CLI uses session model-settings options.json --session ID --revision N and session context --session ID. Changes require an idle session; running turns retain their selected settings and every step records effective provenance.

Shared sdk.slash, desktop and TUI also accept /thinking LEVEL and /effort LEVEL; default clears only effort. /context-window TOKENS|min|half|max preserves effort without changing the remembered model choice. min is 8,192 for an unrestricted model or its smallest declared window; max is its largest supported window; half floors half that maximum and rejects an unsupported result instead of rounding or clamping. Invalid/stale/running-turn changes preserve controls and history, never infer or substitute another model, and use the existing revision-bound session.configure transaction. Protocol 69 advances metadata only; no new event format or retained-content rewrite is required.

To enable memory, clone sdk.settings.get().values, set memory.enabled, then call settings.update with the observed revision. memory.index(projectId) returns a job ID. Wait for a terminal job, inspect its status, and use mcp.readResult(jobId) for the retained bounded result. Failure, partial work and cancellation must not be interpreted as completion.

Project/worktree memory.index/search/graph are explicitly Local, never an active-session env guess. Protocol 27 adds memory.indexSession(sessionId), searchSession(sessionId, text, limit), graphSession(sessionId, path) and state(sessionId) for the service-resolved actual Local/Remote root. State/results expose typed env/profile/peer/path/device/inode/build and source digest; unindexed Remote scope fails memory_missing, not a Local substitute. Source validation uses the actual host's mtime/size/ignore policy; this is cheap freshness, not a hostile timestamp-preserving content proof. Stale hit text is empty, stale graph paths are omitted, and retrieved text stays untrusted. Metadata and vector/chunk/graph rows publish atomically. Original canonical index intent/receipt is event-first; restart or a missing receipt cannot recapture the job. A stop/result-retention failure after publication remains partial and inspectable through memory.state.

Optional memory.useInContext uses that same session binding and whole bounded hits, never truncated JSON/history. Direct model search and builtin MCP search_memory/memory_graph share current source/policy checks. The expanded builtin Remote resource needs a new explicit grant; old two-tool grants do not widen. The worker validates prepared scope/query/tool/root before echoing approved cache data through its owned connector. No provider/refresh/private SSH credential is copied for memory. See the memory contract (not public yet).

Repository script assessments

The owning model uses review_script to receive the entire exact Local file, qualified Sandbox private-stage file or approved public raw URL before recording an explicit safe/unsafe assessment. Native URL reads stay in the actual guest, behind its approved website scope and enforced proxy, never a controller fetch. Findings may be descriptive; a nonempty list does not imply an unsafe verdict. run_script still needs the original source/root, owning attempt and normal execution policy. Model advice never grants permission.

Actual user clients share:

const { review, text } = await sdk.scriptReviews.read(sessionId, reviewId);
await sdk.scriptReviews.approve(
  sessionId, review.id, review.source.digest, review.revision,
  sdk.sessions.get(sessionId)!.revision,
);

Approval accepts only the current exact safe assessment and records script.review_approved with the actual user, command, digest and source revision. It does not advance the model review revision, execute code, grant permission or resume inference. Unsafe assessments instead retain the separate explicit scriptReviews.force(...) API and normal execution approvals. Concurrent/stale decisions and changed source/policy fail explicitly.

Protocol103's native path requires a separately reviewed current worker image; pre-103 native receipts do not qualify it. A native force uses one new model-free owned guest over the same verified private stage. It never inherits Local repository trust, copies a source checkout, changes hard policy or calls a model. review.nativeExecution retains the exact execution/workspace/turn/step and distinct private/guest root digests. The same read response's optional executionResult exposes a retained original observation, including after restart; it is not permission, successful VM cleanup or authority to replay. Missing/interrupted completion remains partial/unknown. Remote and genuinely root-less native script execution remain unsupported.

Inbox exposes one script-review attention entry per pending assessment; desktop groups entries by their original session. Reading/deleting attention never approves a source. Restart exposes retained pending assessments without reinspection or inference. CLI/TUI share /script-review approve ID REVIEW_REV SHA SESSION_REV confirm-reviewed, plus list, read and explicit unsafe force. See the source/approval contract (not public yet).

Skills, scripts and plugins

Standard skills are SKILL.md files with YAML name and description, followed by Markdown instructions. Imports start disabled and grant no permissions. Enabled skills contribute identified metadata/digests; use_skill loads one selected complete body on demand. Neither metadata nor body grants permission. Model proposals retain their model actor and base digest. Human approval installs disabled content; enabling it is a separate explicit action.

A version-1 plugin is a declarative skill bundle:

{
  "schemaVersion": 1,
  "name": "example-conventions",
  "version": "1.0.0",
  "description": "Project conventions",
  "skills": [
    "---\nname: example-style\ndescription: Explicit result types\n---\nPrefer explicit result types at public boundaries."
  ]
}

Enable the plugin before any bundled skill. Disabling the owner prevents its contents from entering context. Arbitrary JavaScript entrypoints, dependency installation and unattended self-modification are not implemented. Reviewed repository-backed marketplace updates and complete disabled bundle rollback use the separate protocol-41 marketplace/capabilities surface above; the legacy skill-only plugins import format does not silently acquire new capabilities.

Approved custom scripts are Node modules receiving JSON on stdin: {"arguments":{},"projectRoot":"/approved/project"}. They emit bounded stdout, must exit, and are exposed as script.CAPABILITY_ID through the internal MCP. They are unsandboxed Local host code. Review the exact source, enable it, then approve each call. The source digest is part of the discovered schema fingerprint; an old approval cannot silently execute changed content.

One native MCP

node bin/moguri.mjs mcp --session SESSION_ID

Configure that command as a stdio MCP in another client. It exposes only moguri_discover_mcps, moguri_find_tools, moguri_auth_status, moguri_call_tool, moguri_read_result, moguri_find_skills and moguri_read_skill. It cannot change settings, credentials, permissions or answer its own approval. Calls wait for the human in the bound idle session, then retain a paged result. Skill discovery/read instead uses freshly checked configured sources, without a model call or new capability installation. Skill text is untrusted guidance, not approval for its instructions or bundled scripts.

Protocol-24 development also exposes mcp.servers(sessionId?) as authoritative, non-connecting metadata for the model gateway, outward MCP, CLI and clients. configured is not entitlement or permission; Remote resources separately report review-required, access-required or unready. Listing reads no access credential and does not execute a configured MCP.

mcp.remotePreview(sessionId, serverId) returns the exact profile-bound host/port/key/root/resource and revision/digest review without reading a token. After explicit human review, grantRemote(sessionId, serverId, digest, settingsRevision, forwardAccess, true) saves the peer/resource grant. forwardAccess is independently false unless explicitly selected; an HTTP bearer can be long-lived and a remote host can retain it. Refresh credentials are never transferred. Probe the changed target and rediscover the scoped catalog before mcp.call; Local or stale schema digests cannot authorize it. The external call needs no model and still waits for its own exact approval.

mcp.remoteCalls(sessionId) and remoteCall(sessionId, operationId) expose original actor/command/execution and retained result, including unknown access or partial effects. Results are bounded to 2 MiB; ordinary readResult pages the corresponding job. revokeRemote(sessionId, serverId, settingsRevision, true) needs neither a ready host nor current permission to execute. Explicit remote.reconcile(executionId) can retain an original late result without re-reading access, replaying a connector or promoting a partial owning turn. The same user controls are available through /mcp-remote and desktop's Remote MCP access, never outward model settings/approval tools.

Backend MCP transports are stdio and Streamable HTTP, using no auth or a scoped OS-keychain bearer credential or explicit OAuth. HTTPS is required except explicitly configured loopback HTTP. Discovery is bounded to 512 tools/64 pages, with 20 tools per SDK response. Tool schemas and server versions are fingerprinted and rechecked at invocation. Credentials are not forwarded through environment variables to stdio children.

Set HTTP transport.auth to "oauth". mcp.oauthBegin(serverId, sessionId?) returns the authorization ID; mcp.oauthStatus(id) exposes its ephemeral URL and lifecycle. Open that URL only on explicit user action. oauthCancel(id) settles a flow; oauthClear(serverId, sessionId?) removes its credential bundle. oauthClient(serverId, clientId, issuer, clientSecret?, sessionId?, redirectUri?) stores a registered client in the secret backend. Optional redirectUri must be an exact fixed loopback callback registered with the issuer; no silent port fallback. Do not put client secrets in settings or command-line arguments.

The official SDK performs S256 PKCE, issuer/resource discovery, registration, exchange and refresh. Resource changes do not reuse another resource's key. New grants require a durable connected decision before use. Cancel/expiry/ restart never replays a callback; revoked/failed refresh never retries a tool or changes to anonymous/bearer auth. Project operations must include the bound session ID, including outward auth-status queries.

The curated internal MCP exposes grep_logs, fetch_page, search_memory and memory_graph. grep_logs searches a literal string in one UTF-8 source up to 1 MiB, returning at most 100 matching lines and 1,000 characters per line, within 12,000 bytes of complete serialized MCP output rather than cut JSON. Results disclose original byte offsets, clipped excerpts, omitted rows and coverage; no match is a successful empty result. Native read_file pages exact source, while search_files supports regex/larger sources. Selective read_file arguments take precedence over mode: "full": the 128-KiB source cap applies only to actual unpaged full reads. Protocol 75 also returns actionable, value-free schema diagnostics for invalid native-tool arguments. The changed Remote builtin resource requires fresh user review; older resource grants are preserved, not silently broadened. Page fetching requires approved HTTPS, pins the resolved public destination, rejects private networks/unsafe redirects and bounds extraction. Tool descriptions, annotations, output and model recommendations remain untrusted data, never permission grants. Project-free discovery/calls exclude workspace tools and approved project scripts.

CLI entrypoints

moguri --help lists the session/project/queue/plan commands. Examples: moguri slash "/read-only" --session ID, moguri session rename NAME --session ID, moguri queue hold prompt.txt --session ID, moguri project get ID, and moguri project set ID settings.json --revision N. Project-free/engagement commands include moguri session create, moguri metachat [REQUEST] --session ID, moguri suggestions preview --session ID, moguri suggestions generate --session ID --digest SHA256, moguri configuration review ID, moguri configuration apply ID --digest SHA256 --acknowledge-config-risk, moguri inbox list, moguri inbox read ID and moguri inbox delete ID. The original attention spelling remains compatible. Use --all-projects only after explicitly reviewing that wider source scope. Destructive removal requires --confirm-remove; default publication requires --confirm-push; repo MCP import requires --confirm-review --digest SHA256. Queue mutations use their observed queue revision, not the session revision.

Dependency cache and project tickets

const { plan } = await sdk.cache.inspect(projectId, "npm");
// Only after the user reviews the plan and accepts OSV metadata disclosure:
const preparation = await sdk.cache.prepare(projectId, "npm", plan.digest, true);
const result = await sdk.jobs.wait(preparation.id!);
if (result.status !== "completed") throw new Error(result.error ?? result.status);

const ticket = await sdk.issues.create(projectId, {
  title: "Add a generated feature", body: "", kind: "feature",
  phaseId: "backlog", pullRequestUrl: null,
});
await sdk.issues.move(ticket.id!, "in-progress", 0);

cache.install is a separate explicit action replacing node_modules, never an automatic consequence of inspection/preparation. It repeats advisory checks, uses private clean staging without project hooks/configuration, and rechecks the lock before replacing the tree. npm requires an installed npm CLI; pnpm's native launcher is pinned with Moguri. Only single-project npm lockfile 2/3 and pnpm lockfile 9/public SHA-512 npm artifacts are qualified. Unsupported managers, workspaces, Git/custom/private resolutions and required lifecycle scripts fail explicitly. A clean advisory result is not a malware-free guarantee.

Boards are local, project-scoped and have no assignee. issues.configure accepts BoardConfig plus its observed revision; occupied phases cannot be removed. Linking a canonical GitHub PR permits bounded read-only observation while Moguri runs, unless the board disables it. Choose the public API or an explicit signed-in GitHub CLI account. A verified merge advances to mergedColumnId; closed/unknown/failed checks and stale responses never do.

Protocol 62 adds optional kanban: {visible, source:"kanban"|"github-issues"|"github-prs", phaseIds}. Boards without a saved preference default hidden, with in-progress/backlog eligible; explicit saved visibility is preserved. kanban.open(projectId) opens/returns the one special idle chat, without inference. sessions.organize(id,{workItemId}, revision?) links only a card from that same project; set workItemUrl:null when replacing a GitHub item.

kanban.continue(originSessionId, issueId?, expectedDraftRevision?) is explicit actual-user delegation for one Local task, isolated worktree, branch push and draft PR. Optional draft consumption accepts only the exact continuation text and revision, never unrelated edits/attachments. kanban.work(runId) reads the independent source/report; kanban.wait(runId) waits only for preparation to settle, not for the PR. kanban.cancel(runId) requests actual owned stop. kanban.inspect(runId,revision,true) releases a terminal interrupted source claim only after jobs/turns settle; it neither resumes nor deletes work. Model/owner/caps, numeric account and source/root bindings are retained. An exact continue work user submission uses this same path; held/recovered or model-authored text cannot acquire it. Failed/restarted work never replays. The model-only project_work tool reads paged board sources and publishes only its already retained exact task. Publication ends the turn without another paid call or executing remaining same-response tools.

Linear is off by default. Enable one team in the board, store the user's personal API key with linear.setToken and explicitly call linear.import. Each page imports at most 50 tickets, preserves provenance and existing local edits, and returns a retained nextCursor. No local issue is exported and no assignee/person data is requested. OAuth/two-way unattended synchronization is not implemented. Credentials are never event payloads, draft text or model input.

CLI examples:

moguri issues list PROJECT_ID
moguri issues create PROJECT_ID issue.json
moguri issues move ISSUE_ID in-progress --revision 0
moguri issues configure PROJECT_ID board.json --revision 0
moguri kanban open PROJECT_ID
moguri kanban items PROJECT_ID github-issues 1
moguri kanban continue ORIGIN_SESSION_ID
moguri kanban work RUN_ID
moguri kanban stop RUN_ID
moguri kanban inspect RUN_ID --revision N --confirm-review
moguri prices
moguri prices refresh anthropic
moguri cache inspect PROJECT_ID npm
moguri cache prepare PROJECT_ID npm PLAN_SHA256 --accept-dependency-metadata
moguri cache install PROJECT_ID npm PLAN_SHA256 --accept-dependency-metadata
moguri linear import PROJECT_ID

issue.json has exactly title, body, kind, phaseId and nullable pullRequestUrl. board.json has columns, mergedColumnId, autoRefreshPrs, githubAccess, linear: { enabled, teamId } and optional kanban. Update/move/archive/configure require the observed --revision. linear token reads piped stdin instead of shell arguments; TUI /linear token uses a dedicated masked editor.

Client lifecycle

node bin/moguri.mjs --help lists supported commands. A normally installed package also supplies the moguri executable. moguri status exposes project and session IDs without printing transcripts or connection credentials. config, prompt, memory, skills, plugins, mcp, agents, dictate and service are SDK adapters. A published desktop binary is supplied separately; starting desktop from source requires the development Electron dependency.

The TUI's Ctrl+G exposes shared settings. Its JSON editor includes all sections and rejects stale revisions. Ctrl+Enter explicitly acknowledges prompt risk and saves; Ctrl+R restores; Esc discards that local editor. See setup (not public yet) for terminal commands, dictation and supported limitations.

Back to the developer docs