@intentic/sandbox-contract 1.155.1 → 1.157.0

package/src/schemas.ts

@@ -181,6 +181,11 @@ export const AgentSummarySchema = z.object({
     // Present while a turn runs: its start, ms since epoch.
     startedAt: z.number().optional(),
     updatedAt: z.number(),
+    // When the agent was last OPENED, ms since epoch — the unread badge's reference point (`updatedAt >
+    // seenAt` ⇒ the agent has done something you haven't looked at). Absent ⇒ never opened. Daemon-side on
+    // purpose: read state is a fact about the WORK, not about one browser profile, so clearing site data or
+    // picking up the phone must not resurrect every badge.
+    seenAt: z.number().optional(),
     attention: AgentAttentionSchema,
     // Completed turns and lifetime tool calls — the card's msgs/tools counters.
     turns: z.number().optional(),
@@ -188,10 +193,26 @@ export const AgentSummarySchema = z.object({
     // The agent's cumulative output (base → branch tip across every repo), refreshed on each land —
     // the card's "12 files · +412 −96" readout. Independent of what has landed.
     diff: z.object({ files: z.number(), insertions: z.number(), deletions: z.number() }).optional(),
+    // When the agent was ARCHIVED (ms epoch) — off the board, but nothing lost: its checkout was retired
+    // (worktree removed) while the agent/<id> branch, the transcript, and every counter stayed. Absent ⇒ live
+    // on the board. Archived agents are excluded from the roster the fleet renders; `agents.archived` lists
+    // them, `agents.unarchive` brings one back, and the next turn re-attaches its worktree from the branch.
+    archivedAt: z.number().optional(),
 });
 export type AgentSummary = z.infer<typeof AgentSummarySchema>;
 export const AgentsListSchema = z.object({ agents: z.array(AgentSummarySchema) });
 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).
+export const AgentArchiveSchema = z.object({ ids: z.array(z.string().min(1)).max(500).optional() });
+export const AgentIdsSchema = z.object({ ids: z.array(z.string().min(1)).min(1).max(500) });
+// What actually MOVED, and deliberately NOT the roster afterwards. Two archives in flight at once each finish
+// holding a full-roster snapshot from a different instant, so a client that swapped one in wholesale would let
+// 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) });
+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) });
 export const AgentFileDiffQuerySchema = z.object({ id: z.string().min(1), repo: z.string().min(1), path: z.string().min(1) });
@@ -262,10 +283,11 @@ export const SteerSchema = z.object({ conversationId: z.string().min(1), text: z
 export const StopTurnSchema = z.object({ conversationId: z.string().min(1) });
 
 // ---- claude subscription usage ----
-// Which usage window is active for a Claude account, how much of it is spent, and when it resets. Two readers,
-// so it lives here rather than beside the stream frames: the SDK's rate_limit_event rides it out on the agent
-// stream (see the `rate_limit_info` frame in events.ts), and the daemon persists the latest snapshot per
-// account so `/claude/accounts` can answer "how much is left on each" without spending a turn to find out.
+// The GATE signal: whether the provider is letting turns through right now, and — when it is refusing — which
+// window is binding and when it lifts. This is the SDK's rate_limit_event, mapped one-to-one, and it is only
+// ever about the CURRENT moment. It is deliberately NOT the thing the headroom displays read: the event names a
+// single window (whichever the CLI considered binding), which is how "weekly 1%" ended up standing in for an
+// account that was really at 98% on another weekly pool.
 export const RateLimitInfoSchema = z.object({
     status: z.enum(["allowed", "allowed_warning", "rejected"]),
     resetsAt: z.number().optional(), // epoch seconds
@@ -274,11 +296,32 @@ export const RateLimitInfoSchema = z.object({
 });
 export type RateLimitInfo = z.infer<typeof RateLimitInfoSchema>;
 
-// The persisted view: a snapshot plus when it was taken. Within one window utilization only climbs, so a
-// snapshot stays a valid FLOOR until `resetsAt` passes — after that the window has rolled over and the store
-// drops it rather than reporting a stale number. `measuredAt` is epoch MS (matching connectedAt), while
-// `resetsAt` stays epoch SECONDS (matching the SDK frame) — they are deliberately different units.
-export const AccountUsageSchema = RateLimitInfoSchema.extend({ measuredAt: z.number() });
+// One plan-limit pool. `kind` is the provider's own key ('five_hour' | 'seven_day' | 'seven_day_opus' |
+// 'seven_day_sonnet' | 'model:Fable' | …) rather than an enum we'd have to keep in step with the provider: an
+// unrecognised pool is shown under its raw key, which is far better than being silently folded into a
+// neighbour. `label` is the provider's OWN display name where it supplies one (the per-model buckets do) — it
+// wins over anything we'd infer, because the model names in a plan's limits are the provider's to rename.
+// `resetsAt` is epoch SECONDS (matching the SDK's frame).
+export const UsageWindowSchema = z.object({
+    kind: z.string(),
+    label: z.string().optional(),
+    utilization: z.number(), // 0-100
+    resetsAt: z.number().optional(),
+});
+export type UsageWindow = z.infer<typeof UsageWindowSchema>;
+
+// An account's headroom: EVERY window the provider reports, read together, plus when the reading was taken.
+// All of them, not the binding one, because "which pool is binding" changes between turns and a reader
+// comparing accounts needs the same pools on every row. Sourced from the CLI's own usage endpoint at turn end
+// (see claudeUsageWindows) — a control request, so it costs no tokens.
+//
+// Within one window utilization only climbs, so an un-reset window stays a valid FLOOR however old it is; past
+// its `resetsAt` it describes a pool that no longer exists and the store drops it. `measuredAt` is epoch MS
+// (matching connectedAt) — deliberately a different unit from the windows' seconds.
+export const AccountUsageSchema = z.object({
+    windows: z.array(UsageWindowSchema),
+    measuredAt: z.number(),
+});
 export type AccountUsage = z.infer<typeof AccountUsageSchema>;
 
 // ---- provider oauth ----
@@ -376,7 +419,6 @@ export const ModelsSchema = z.object({ models: z.array(ModelSchema), default: z.
 export const SessionIdParamSchema = z.object({ id: z.string() });
 export const SessionSummarySchema = z.object({ id: z.string(), title: z.string(), updatedAt: z.number() });
 export const SessionsListSchema = z.object({ sessions: z.array(SessionSummarySchema) });
-export const SessionTranscriptSchema = z.object({ messages: z.array(SessionTranscriptMessageSchema) });
 
 // ---- settings: per-sandbox agent settings (.intentic/settings.json) ----
 // Small user-owned config the /settings routes edit and streamAgent reads — all opt-in booleans the owner
@@ -422,6 +464,11 @@ export const SandboxSettingsSchema = z.object({
     outputCleaners: z.string().default("off"),
     outputHoldout: z.number().min(0).max(1).default(0),
     filterBackend: z.enum(["native", "rtk"]).default("native"),
+    // How long a finished agent stays on the board before it is archived automatically (days; 0 ⇒ never).
+    // Unlike every other flag here this one defaults ON, because the lane it governs is the board's only
+    // terminal state: without a sweep the Finished lane grows for the life of the sandbox, and each card it
+    // holds is a live worktree checkout, not just a row.
+    agentRetentionDays: z.number().min(0).max(365).default(3),
 });
 export type SandboxSettings = z.infer<typeof SandboxSettingsSchema>;
 
@@ -806,6 +853,30 @@ export const WorkspaceSearchResultSchema = z.object({
 });
 export type WorkspaceSearchResult = z.infer<typeof WorkspaceSearchResultSchema>;
 
+// ---- workspace setup (dependency readiness) ----
+
+// One project under /work and whether its dependencies are actually installed. A drop omits node_modules/.venv
+// on purpose, so a freshly imported project is present-but-unusable until this says "ready" — the import UI,
+// the agent's post-edit type-check, and the agent's turn context all gate on it.
+// `dir` is root-relative ("" = the workspace root itself); `manager` is the real binary (pnpm/npm/uv/…);
+// `evidence` is the file that decided it ("pnpm-lock.yaml"), so the UI can show WHY, not just what.
+// state: ready | installing | needs-setup | unsupported (manager absent from this sandbox — `manager` names it).
+export const ProjectSetupSchema = z.object({
+    dir: z.string(),
+    ecosystem: z.enum(["node", "python"]),
+    manager: z.string(),
+    command: z.string(),
+    evidence: z.string(),
+    state: z.enum(["ready", "installing", "needs-setup", "unsupported"]),
+});
+export type ProjectSetup = z.infer<typeof ProjectSetupSchema>;
+export const WorkspaceSetupSchema = z.object({ projects: z.array(ProjectSetupSchema) });
+export type WorkspaceSetup = z.infer<typeof WorkspaceSetupSchema>;
+// Install these projects' dependencies. Dirs already ready, already installing, or whose manager is missing are
+// skipped server-side, so a stale client list can't spawn redundant installs — `started` is what actually ran.
+export const WorkspaceInstallSchema = z.object({ dirs: z.array(z.string()).min(1) });
+export const WorkspaceInstallResultSchema = z.object({ started: z.array(z.string()) });
+
 // ---- workspace repos ----
 
 // Every discovered repo's id (root-relative dir under /work), sorted — roles included.
@@ -1379,6 +1450,42 @@ export type ExtensionProcessStatus = z.infer<typeof ExtensionProcessStatusSchema
 // /webchat/<id>/message and the agent's reply streams back over SSE. Its address is the public automation id, so
 // allowedOrigins (the widget's embed sites) + a per-conversation rate limit are its abuse boundary — no secret
 // token can live in a browser.
+// `workspace` fires from the sandbox's OWN codebase instead of the outside world — see WorkspaceEventKindSchema.
+
+// What the daemon emits as the fleet works, and what a `workspace` trigger names. These are the events a code
+// CHORE runs on (continuous review, post-land checks): the daemon is both producer and consumer, so unlike
+// `event` there is no token and no route — nothing outside the sandbox can reach them.
+//
+// The two OVERLAP on the common path: a clean turn auto-lands, firing both. A chore should name exactly one.
+// `turn.settled` fires once per isolated turn whatever its outcome, so it also covers the errored and
+// conflicted turns most worth a second pair of eyes, and it fires while the user is still looking at the diff —
+// before they decide to land. `agent.landed` fires only when work actually reached the main tree, including an
+// explicit Land from the review panel long after the turn ended.
+export const WorkspaceEventKindSchema = z.enum(["turn.settled", "agent.landed"]);
+export type WorkspaceEventKind = z.infer<typeof WorkspaceEventKindSchema>;
+
+// The payload a workspace-triggered wake carries: one JSON object, in $AUTOMATION_PAYLOAD for the guard and
+// appended to the prompt for the turn.
+//
+// `repos` names the change to look at as an OPEN span — `git -C <dir> diff <from>`, with no upper bound. Each
+// `from` is where that repo stood before the turn (its last landed tip, or the base it branched from); the
+// other end is deliberately the working tree rather than a sha, because a turn that ERRORED left its work
+// uncommitted in the worktree and a commit-to-commit span would report it as nothing at all. `dir` is that
+// repo's dir inside the agent's own checkout, so a chore reads the agent's work without touching /work.
+//
+// No diffstat rides along on purpose: the registry's counts are refreshed at land, so an errored or conflicted
+// turn would carry stale numbers, and a guard that wants a size threshold gets the true one from
+// `git -C <dir> diff --numstat <from>` for the price of one spawn.
+export const WorkspaceEventSchema = z.object({
+    event: WorkspaceEventKindSchema,
+    agentId: z.string(),
+    title: z.string().optional(),
+    branch: z.string(),
+    outcome: z.enum(["landed", "conflict", "idle", "error"]),
+    repos: z.array(z.object({ repo: z.string(), from: z.string(), dir: z.string() })),
+});
+export type WorkspaceEvent = z.infer<typeof WorkspaceEventSchema>;
+
 export const TriggerSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("schedule"), cron: z.string().min(1) }),
     z.object({ kind: z.literal("event"), token: z.string().min(1).optional() }),
@@ -1391,6 +1498,8 @@ export const TriggerSchema = z.discriminatedUnion("kind", [
         // webchat only: the website origins allowed to POST to the widget endpoint. Absent/empty ⇒ none admitted.
         allowedOrigins: z.array(z.string()).optional(),
     }),
+    // `repo` narrows to events whose span touches one workspace repo ("root" or a repo id); absent ⇒ any.
+    z.object({ kind: z.literal("workspace"), event: WorkspaceEventKindSchema, repo: z.string().min(1).optional() }),
 ]);
 export type Trigger = z.infer<typeof TriggerSchema>;
 
@@ -1408,6 +1517,11 @@ export const AutomationSchema = z.object({
     model: z.string().optional(),
     // When true, a fire doesn't wake the agent — it's held in the approvals queue until the owner approves.
     requireApproval: z.boolean().optional(),
+    // A code CHORE: maintenance of THIS codebase rather than a reaction to the outside world. Purely a
+    // classification — the daemon fires a chore exactly like any other automation — but it cannot be derived
+    // from the trigger, which is why it is stored: a nightly `pnpm audit` sweep and a nightly Stripe poll are
+    // both `schedule`, and belong on different shelves. Absent ⇒ an ordinary automation.
+    chore: z.boolean().optional(),
     enabled: z.boolean(),
 });
 export type Automation = z.infer<typeof AutomationSchema>;