@intentic/sandbox-contract 1.157.0 → 1.159.0

package/src/schemas.ts

@@ -54,6 +54,24 @@ export type EditorContext = z.infer<typeof EditorContextSchema>;
 // and filesystem paths — the regex is the injection guard. Shared by the turn input and the attach input.
 const ConversationIdSchema = z.string().regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/);
 
+// Where a conversation came from when nobody typed it into the browser: an automation wake carrying a message
+// from OUTSIDE the sandbox (a Discord mention, a web-chat visitor, a webhook). Such a wake runs as an ordinary
+// isolated conversation — registry entry, worktree, chat tab, land flow — and this is the only thing that
+// distinguishes it on the surface: the card's provenance line and the reason its first prompt is not the
+// user's. Set daemon-side by the dispatcher that received the message; the browser never sends one.
+export const AgentOriginSchema = z.object({
+    // The automation whose configured prompt opened the conversation.
+    automationId: z.string(),
+    // The listener provider that received the message ("discord", "webchat", …) or "webhook" for an event
+    // trigger. An open string for the same reason Trigger.provider is: sources are extension-declared.
+    provider: z.string(),
+    // The external thread it arrived on — a Discord channel id, a widget conversation id. Absent for webhooks.
+    channelId: z.string().optional(),
+    // Who sent it, as the source names them.
+    author: z.string().optional(),
+});
+export type AgentOrigin = z.infer<typeof AgentOriginSchema>;
+
 // How tool calls are gated — the Claude Agent SDK's PermissionMode, narrowed to the four the composer offers
 // (the SDK also has 'dontAsk'/'auto', which have no UI here). The user picks one per turn AND the agent can
 // move itself between them mid-turn, so this is both a turn input and the payload of the `mode` frame.
@@ -89,6 +107,10 @@ export const AgentTurnSchema = z
         // When true, the turn runs in the conversation's isolated git worktree (created lazily on first use)
         // instead of the shared /work tree — the parallel-agents mode. Requires conversationId.
         isolated: z.boolean().optional(),
+        // Set ONLY by the daemon's own automation dispatchers: this turn opens a conversation on behalf of an
+        // outside message rather than a user. Recorded on the registry entry so the fleet can say where the
+        // agent came from. Requires conversationId — there is nothing to record it on otherwise.
+        origin: AgentOriginSchema.optional(),
         // The client-held transcript of a conversation that just switched provider/account: seeds the FIRST
         // turn of the replacement session. The daemon folds it into the prompt as one role-attributed context
         // preamble for every runtime. Mutually exclusive with sessionId — a resumed session has its context.
@@ -114,6 +136,9 @@ export const AgentTurnSchema = z
     })
     .refine((turn) => turn.isolated !== true || turn.conversationId !== undefined, {
         message: "isolated requires conversationId",
+    })
+    .refine((turn) => turn.origin === undefined || turn.conversationId !== undefined, {
+        message: "origin requires conversationId",
     });
 export type AgentTurn = z.infer<typeof AgentTurnSchema>;
 
@@ -169,6 +194,9 @@ export const AgentSummarySchema = z.object({
     account: z.string().optional(),
     // The worktree branch (agent/<id>); absent for a non-isolated (main-tree) conversation.
     branch: z.string().optional(),
+    // Present when the conversation was opened by an outside message rather than by the user (see
+    // AgentOriginSchema) — the card's provenance line. Absent ⇒ the user started it.
+    origin: AgentOriginSchema.optional(),
     // The ROOT repo's short base sha — the checkout moment's display identity. Per-repo bases stay
     // daemon-internal (agents.diff already reports against them).
     base: z.string().optional(),
@@ -200,7 +228,12 @@ export const AgentSummarySchema = z.object({
     archivedAt: z.number().optional(),
 });
 export type AgentSummary = z.infer<typeof AgentSummarySchema>;
-export const AgentsListSchema = z.object({ agents: z.array(AgentSummarySchema) });
+// `rev` is the registry revision this roster was read at — a counter the daemon bumps on every registry change.
+// It is what makes the browser's optimistic writes safe: the fleet is published as full snapshots (last frame
+// wins), so without an ordering stamp a roster READ before a mutation but delivered after it silently puts the
+// mutated agents back. The browser drops any roster older than the newest it has applied, and holds its own
+// pending change until a roster at or past the revision that applied it arrives. See useAgents.ts.
+export const AgentsListSchema = z.object({ agents: z.array(AgentSummarySchema), rev: z.number() });
 export const AgentIdSchema = z.object({ id: z.string().min(1) });
 // archive's input: the agents to take off the board. Absent `ids` ⇒ every finished agent that is archivable
 // right now (the lane header's "Clear"); unarchive always names its ids (a restore, or a bulk archive's undo).
@@ -211,7 +244,9 @@ export const AgentIdsSchema = z.object({ ids: z.array(z.string().min(1)).min(1).
 // the slower response resurrect what the faster one just filed away — a delta composes where a snapshot races.
 // Whole summaries rather than ids because the receiving side has to SHOW them (the archive list, and the agent
 // detail page addressed by id); the ids "Undo" needs come off them for free.
-export const AgentsMovedSchema = z.object({ moved: z.array(AgentSummarySchema) });
+// The agents an archive/unarchive actually moved, plus the registry revision that applied the move — the
+// browser holds its optimistic add/remove of exactly these ids until it sees a roster at or past `rev`.
+export const AgentsMovedSchema = z.object({ moved: z.array(AgentSummarySchema), rev: z.number() });
 export type AgentsMoved = z.infer<typeof AgentsMovedSchema>;
 // rename's input: the user-chosen display title (bounded like sanitizeTitle's cap).
 export const AgentRenameSchema = z.object({ id: z.string().min(1), title: z.string().trim().min(1).max(80) });
@@ -276,8 +311,20 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
 export type AgentReply = z.infer<typeof AgentReplySchema>;
 // Steering: a user message delivered INTO the running turn (injected between tool calls, Claude Code style),
 // keyed by the conversation whose turn is in flight. NOT_FOUND when no steerable turn is running — the client
-// then falls back to a fresh send.
-export const SteerSchema = z.object({ conversationId: z.string().min(1), text: z.string().min(1).max(20_000) });
+// then holds the message in its queue and sends it as the next turn instead. Carries everything a turn's own
+// prompt can carry (files, the editor-context chip), because "add more while it works" is worth nothing if it
+// only takes bare text: the daemon folds the same notes into the injected message that a fresh turn gets.
+export const SteerSchema = z
+    .object({
+        conversationId: z.string().min(1),
+        text: z.string().max(20_000),
+        attachments: z.array(z.string().min(1)).max(20).optional(),
+        editorContext: EditorContextSchema.optional(),
+    })
+    // An attachment-only steer (a screenshot dropped in mid-turn) is legal; an entirely empty one is not.
+    .refine((steer) => steer.text.trim().length > 0 || (steer.attachments?.length ?? 0) > 0, {
+        message: "text or attachments required",
+    });
 // True cancel for the conversation's in-flight turn — aborts the agent daemon-side, unlike closing the
 // /agent fetch (which sends no cancel frame).
 export const StopTurnSchema = z.object({ conversationId: z.string().min(1) });
@@ -783,6 +830,12 @@ export const WorkspaceChildrenSchema = z.object({
 export type WorkspaceChildren = z.infer<typeof WorkspaceChildrenSchema>;
 export const WorkspaceFileQuerySchema = z.object({ path: z.string().min(1) });
 export const WorkspaceFileSchema = z.object({ path: z.string(), content: z.string() });
+// Resolve a file reference an agent (or a compiler, or a terminal) NAMED to the workspace path it means. Prose
+// paths are routinely partial — a model that has been discussing `_apps/web/src` writes
+// `pages/workspace/Foo.vue` — so a clickable mention has to be matched as a path SUFFIX against the real tree,
+// not read as root-relative. `path` is absent when nothing in the workspace ends in that reference.
+export const WorkspaceResolveQuerySchema = z.object({ path: z.string().min(1).max(512) });
+export const WorkspaceResolveSchema = z.object({ path: z.string().optional() });
 // Direct file management over the /work tree (delete / new folder / rename+move / copy). Byte writes + the
 // editor's text save go through the plain POST /workspace/upload route (a body doesn't fit oRPC), not here.
 export const WorkspaceDirSchema = z.object({ path: z.string().min(1) });
@@ -1534,6 +1587,10 @@ export const AutomationApprovalSchema = z.object({
     automationId: z.string(),
     // The event/listener payload the wake would have carried; absent for schedule triggers.
     payload: z.string().optional(),
+    // The provenance + title the held wake would have opened its conversation with — snapshotted alongside the
+    // payload so an approved external wake surfaces on the fleet exactly as an auto one would have.
+    origin: AgentOriginSchema.optional(),
+    title: z.string().optional(),
     createdAt: z.number(),
 });
 export type AutomationApproval = z.infer<typeof AutomationApprovalSchema>;
@@ -1684,7 +1741,8 @@ export type PortForwardResult = z.infer<typeof PortForwardResultSchema>;
 // is the /system/terminal WebSocket, not oRPC): `shell` = a web-* session the user opened (numbered pill),
 // `panel` = a panel-* dev-server session (labeled by its panel key, started via Start; running:false =
 // untracked, e.g. a finished one-shot job's lingering shell), `agent` = an agent-* session the Claude agent's
-// Bash commands run in (live-watchable, AI-marked in the UI), `job` = a job-* session the daemon's terminal
+// Bash commands run in (live-watchable, AI-marked in the UI; running:false once every window is a finished
+// command's dead pane, which is what lets the panel sweep it), `job` = a job-* session the daemon's terminal
 // runner executes user-triggered flows in (capability adds, infra check), `process` = a managed background
 // process riding a panel session (an extension's declared processes, dockerd) — surfaced in the panel's
 // background-processes popover with read-only log views, never as a killable tab; running is the actual