@intentic/sandbox-contract 1.321.0 → 1.323.0

package/src/schemas/providers/plan-limits.ts

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { ChildRunSchema } from "../../events/requests.js";
 import { TRANSLATOR_PROVIDERS, type TranslatorProvider } from "../../models/provider-specs.js";
-import { AgentHarnessSchema, AgentProviderSchema, EditorContextSchema } from "../agent.js";
+import { AgentHarnessSchema, AgentProviderSchema, ConversationIdSchema, EditorContextSchema } from "../agent.js";
 import { MENTION_LIMIT } from "../../text/mentions.js";
 // Headroom is one shape shared by every provider, not a Claude idea others imitate: a native account and a routed
 // subscription differ in who holds the credential, never in what a reading is. Every surface that draws a percentage
@@ -32,7 +32,9 @@ export const UsageUnreadSchema = z.object({
     since: z.number().describe("When re-reading this account first failed, in milliseconds. It has failed on every attempt since."),
     reason: z
         .string()
-        .describe("Why, in the provider's own words where it gave some (\"Verify your account to continue.\"). Short enough to print; never a pasted response body."),
+        .describe(
+            'Why, in the provider\'s own words where it gave some ("Verify your account to continue."). Short enough to print; never a pasted response body.',
+        ),
 });
 export type UsageUnread = z.infer<typeof UsageUnreadSchema>;
 // Every window kept, not just the binding one, since which pool binds changes between turns. Utilization only climbs
@@ -202,18 +204,27 @@ export const AgentReplySchema = z.discriminatedUnion("kind", [
             .record(z.string(), z.array(z.string()))
             .optional()
             .describe("What you chose, keyed by the question, with the chosen labels or your own words."),
+        attachments: z
+            .record(z.string(), z.array(z.string()))
+            .optional()
+            .describe(
+                "Files that go with your own-words answer, keyed by the question, as workspace-relative paths of files already uploaded (a screenshot, a mock-up).",
+            ),
         cancelled: z
             .boolean()
             .optional()
             .describe("Dismissing it instead, which tells the agent to carry on using sensible defaults rather than leaving it waiting."),
     }),
-    // "always" may be narrowed further by the SDK's own suggestions.
+    // "always" may be narrowed further by the SDK's own suggestions. "everything" is the conversation-wide yes the card's
+    // Allow menu offers: this call, and every later request in the conversation a person could have allowed once.
     z.object({
         kind: z.literal("permission").describe("Answering a request to use a tool."),
         requestId: z.string().min(1).describe("Which card you are answering."),
         decision: z
-            .enum(["once", "always", "deny"])
-            .describe("Once allows this call alone; always allows that whole tool for the rest of the conversation; no blocks it."),
+            .enum(["once", "always", "everything", "deny"])
+            .describe(
+                "Once allows this call alone; always allows what the request's always-label names (a tool, a rule, a secret) for the rest of the conversation; everything allows this call and every later request in this conversation that an allow-once could settle, until it is taken back on Grants; no blocks it. A request that always asks (alwaysAsks) reads everything as once.",
+            ),
         feedback: z.string().optional().describe("Why not, which goes back to the model as the reason."),
         // Whole, not a patch: effort or an account named for one model means nothing on another.
         child: ChildRunSchema.optional().describe(
@@ -401,6 +412,28 @@ export const QueueResumeSchema = z.object({
     ),
 });
 export type QueueResume = z.infer<typeof QueueResumeSchema>;
+// Re-times what a conversation's queue holds: the same messages, booked for another instant or for after another
+// conversation's work lands. One of the two, never both, since a hold waits on exactly one thing.
+export const QueueScheduleSchema = z
+    .object({
+        conversationId: z.string().min(1).describe("Whose queue."),
+        sendAt: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Send what waits at this instant (epoch milliseconds) instead. At most a month ahead; an instant already past sends it now."),
+        sendAfter: ConversationIdSchema.optional().describe(
+            "Send what waits once that conversation has finished and all of its work has landed in the workspace, instead. Sent now when it has nothing running and nothing left to land.",
+        ),
+    })
+    .refine((input) => (input.sendAt === undefined) !== (input.sendAfter === undefined), {
+        message: "name exactly one of sendAt and sendAfter",
+    })
+    .refine((input) => input.sendAfter !== input.conversationId, {
+        message: "a conversation cannot wait for its own work to land",
+    });
+export type QueueSchedule = z.infer<typeof QueueScheduleSchema>;
 // Moves a conversation to another account of the provider it runs on: the one command that changes who pays, so the
 // account a conversation runs on is always the daemon's record and never a window's guess.
 export const SwitchAccountSchema = z.object({

package/src/schemas/providers/usage.ts

@@ -42,11 +42,16 @@ export const UsageTurnSchema = z.object({
     turns: z
         .number()
         .describe("The provider's own count for the request, since one exchange can be several under the hood. One when it reported none."),
-    inputTokens: z.number().describe("Tokens sent."),
+    inputTokens: z.number().describe("Uncached input tokens, excluding cache reads and cache writes."),
     outputTokens: z.number().describe("Tokens received."),
     cacheReadTokens: z.number().describe("Tokens served from cache, which cost less."),
     cacheCreationTokens: z.number().describe("Tokens written to cache, which cost more up front and less afterwards."),
     costUsd: z.number().describe("What it cost, in dollars."),
+    // Whether `costUsd` was reported by the vendor (true or absent) or is zero only because the vendor does not price
+    // its calls (false). Old rows before this field was added carry no marker, which readers treat as known: they
+    // already recorded a real number. Runtimes like Codex and Cursor report tokens but no cost, so their turns land
+    // with `costUsd: 0, costKnown: false` rather than silently claiming they were free.
+    costKnown: z.boolean().optional().describe("False when the vendor did not report a cost and the recorded zero is a placeholder, not a price. Absent or true means the cost is real."),
     durationMs: z.number().describe("How long it took, in milliseconds."),
     // Arm of the search-teaching experiment; stable per conversation. Absent means unmeasured.
     iqSearchArm: z.boolean().optional(),
@@ -126,11 +131,14 @@ export const UsageRollupRowSchema = z.object({
     harness: z.string().describe("Which agentic loop."),
     conversationId: z.string().optional().describe("Which conversation."),
     turns: z.number().describe("Turns in this group."),
-    inputTokens: z.number().describe("Tokens sent."),
+    inputTokens: z.number().describe("Uncached input tokens, excluding cache reads and cache writes."),
     outputTokens: z.number().describe("Tokens received."),
     cacheReadTokens: z.number().describe("Tokens served from cache."),
     cacheCreationTokens: z.number().describe("Tokens written to cache."),
     costUsd: z.number().describe("What the group cost, in dollars."),
+    // True when every turn in the group reported its cost; false when at least one did not, making `costUsd` a
+    // lower bound rather than the true total. Absent on rollups from before this field existed.
+    costKnown: z.boolean().optional().describe("False when the cost includes unpriced turns and is a lower bound rather than the true total."),
     durationMs: z.number().describe("Time spent, in milliseconds."),
 });
 export type UsageRollupRow = z.infer<typeof UsageRollupRowSchema>;

package/src/schemas/push.ts

@@ -52,6 +52,13 @@ export const PushNotificationSchema = z.object({
         .describe(
             "Keep it on screen until it is dismissed. Used when the agent is waiting for you, where one that fades away is a question that went unanswered in silence.",
         ),
+    // Optional so an older service worker or relay, which ignores it, still shows the replacement under the same tag.
+    silent: z
+        .boolean()
+        .optional()
+        .describe(
+            "Arrive without sound or vibration. Used for the replacement that says an ask stopped waiting: it takes the waiting one's place under the same tag, and is news nobody has to act on.",
+        ),
 });
 export type PushNotification = z.infer<typeof PushNotificationSchema>;
 export const PushConfigSchema = z.object({

package/src/state/workspace-state.test.ts

@@ -29,7 +29,7 @@ const AUTOMATIONS: readonly FileContribution[] = [
 
 describe(`staleQueryKeys`, () => {
     it(`maps a manifest write to the queries it makes stale`, () => {
-        expect(staleQueryKeys([`.intentic/config/capabilities.json`], [])).toEqual([`capabilities`, `environment`, `panels`, `manifests`]);
+        expect(staleQueryKeys([`.intentic/config/capabilities.json`], [])).toEqual([`capabilities`, `extensions`, `environment`, `panels`, `manifests`]);
     });
 
     it(`refreshes the unreadable-manifest notice for the four files a person hand-edits`, () => {
@@ -72,6 +72,7 @@ describe(`staleQueryKeys`, () => {
         // A capability add recomposes the overlay, so both paths claim environment; one entry, not two.
         expect(staleQueryKeys([`.intentic/config/capabilities.json`, `.intentic/config/environment.Dockerfile`], [])).toEqual([
             `capabilities`,
+            `extensions`,
             `environment`,
             `panels`,
             `manifests`,
@@ -160,7 +161,9 @@ describe(`WORKSPACE_STATE_FILES`, () => {
         for (const file of WORKSPACE_STATE_FILES.filter((entry) => entry.invalidates.length > 0)) {
             const isFamilyPrefix = file.path.endsWith(`.`);
             // .md is the safety policy: the one state file a model reads as prose rather than a parser reading JSON.
-            const isFile = file.path.endsWith(`.json`) || file.path.endsWith(`.Dockerfile`) || file.path.endsWith(`.md`);
+            // .toon is the field-notes brief, read by rank into every turn.
+            const isFile =
+                file.path.endsWith(`.json`) || file.path.endsWith(`.Dockerfile`) || file.path.endsWith(`.md`) || file.path.endsWith(`.toon`);
             expect(isFile || isFamilyPrefix || file.path.endsWith(`/`), file.path).toBe(true);
         }
     });
@@ -348,6 +351,9 @@ describe(`VERSIONED_STATE_PATHS`, () => {
             `${STATE_DIR}/config/extension-settings.json`,
             // Per-extension update posture (notify/agent/auto): a standing decision on what may run unattended.
             `${STATE_DIR}/config/extension-update-policy.json`,
+            // The field-notes brief every turn opens with. Tracked so the automation that rewrites it, which always
+            // runs isolated, can land its rewrite at all; and a new revision is worth a reviewable diff.
+            `${STATE_DIR}/config/field-notes.toon`,
             // Which commands count as heavy, and how many may run at once; a shared-box decision worth a `git log`
             // line.
             `${STATE_DIR}/config/heavy-commands.json`,

package/src/state/workspace-state.ts

@@ -42,10 +42,12 @@ const STATE_FILES = [
     // Holds no credential: values are vaulted (capabilities-store.ts's withSecretVault) and read back rehydrated; the
     // vaulted keys are the complement of what `echo` exposes (capabilities/credentials/secret-fields.ts). `carry` because
     // composeEnvironment reads Dockerfile fragments from here; `versioned` because connecting a capability is a
-    // consequential change worth reviewing.
+    // consequential change worth reviewing. `extensions` because an installed extension is a capability entry: the
+    // daemon writes this file once the checkout is in place, so an install an agent or another tab made reaches an open
+    // Extensions view without a reload.
     {
         path: ".intentic/config/capabilities.json",
-        invalidates: ["capabilities", "environment", "panels", "manifests"],
+        invalidates: ["capabilities", "extensions", "environment", "panels", "manifests"],
         portability: "carry",
         versioned: true,
     },
@@ -107,6 +109,14 @@ const STATE_FILES = [
         portability: "derived",
         note: "The target starts its own record of what it decided.",
     },
+    // What the privacy shield's gateway did with each model request: kinds and counts, never a value. `derived`: evidence
+    // about this machine, self-trimming, not carried.
+    {
+        path: ".intentic/local/privacy-log.json",
+        invalidates: ["privacy-log"],
+        portability: "derived",
+        note: "The target starts its own record of what its shield did.",
+    },
     // Apps the daemon starts on every boot (scaffold/autostart.ts). `carry`: an exported workspace should start the
     // same things. Invalidates nothing: the browser reads what's running off `/panels`, not this file.
     {
@@ -120,6 +130,17 @@ const STATE_FILES = [
     // Bash command. `carry`: a property of the workspace, not the machine. `versioned`: raising the limit is a decision
     // worth a diff.
     { path: ".intentic/config/heavy-commands.json", invalidates: ["settings"], portability: "carry", versioned: true },
+    // The field-notes brief composed into every turn (agent-context field-notes.ts), rewritten by the monthly
+    // `field-notes` automation. `versioned` is load-bearing, not just reviewability: automation wakes always run
+    // isolated, and an unversioned path is excluded from the root repo, so the rewrite would never leave its worktree.
+    // Feeds the agent-settings row (`settings.fieldNotes`).
+    {
+        path: ".intentic/config/field-notes.toon",
+        invalidates: ["settings"],
+        portability: "carry",
+        versioned: true,
+        outsideWriter: "the field-notes automation's agent turn (the daemon only reads it, through FIELD_NOTES_FILE)",
+    },
     // Last-fired stamps for the rule table. `derived`: records what happened on this machine, not carried.
     {
         path: ".intentic/local/rule-firings.json",
@@ -163,6 +184,15 @@ const STATE_FILES = [
         why: "Declared by the intentic.automations extension's contributes.files, `automations` is its query key, not core's.",
         portability: "carry",
     },
+    // How far the scheduler has accounted for each schedule's clock, so a boot fires the moments it slept through
+    // (automations/schedule-coverage.ts). `carry`: it travels with the automations it measures, or a restored sandbox
+    // would read every one as never armed.
+    {
+        path: ".intentic/records/automation-schedule.json",
+        invalidates: [],
+        why: "Scheduler bookkeeping nothing in the browser renders: what a catch-up fire produces reaches the run ledger, which carries the automations key.",
+        portability: "carry",
+    },
     {
         path: ".intentic/records/approvals/",
         invalidates: [],