@intentic/sandbox-contract 1.337.0 → 1.339.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentic/sandbox-contract",
-  "version": "1.337.0",
+  "version": "1.339.0",
   "description": "oRPC wire contract for the intentic sandbox daemon, shared by the daemon and its browser client",
   "license": "MIT",
   "type": "module",
@@ -238,6 +238,17 @@
         "default": "./dist/policy/identity-assertion.js"
       }
     },
+    "./keyring-seal": {
+      "types": "./dist/policy/keyring-seal.d.ts",
+      "import": {
+        "@intentic/src": "./src/policy/keyring-seal.ts",
+        "default": "./dist/policy/keyring-seal.js"
+      },
+      "require": {
+        "@intentic/src": "./src/policy/keyring-seal.ts",
+        "default": "./dist/policy/keyring-seal.js"
+      }
+    },
     "./owner-ticket": {
       "types": "./dist/policy/owner-ticket.d.ts",
       "import": {
@@ -336,13 +347,24 @@
         "@intentic/src": "./src/protocol/doors/webext-links.ts",
         "default": "./dist/protocol/doors/webext-links.js"
       }
+    },
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": {
+        "@intentic/src": "./src/*.ts",
+        "default": "./dist/*.js"
+      },
+      "require": {
+        "@intentic/src": "./src/*.ts",
+        "default": "./dist/*.js"
+      }
     }
   },
   "dependencies": {
-    "@intentic/base": "1.337.0",
-    "@intentic/constants": "1.337.0",
-    "@intentic/extension-manifest": "1.337.0",
-    "@intentic/registry": "1.337.0",
+    "@intentic/base": "1.339.0",
+    "@intentic/constants": "1.339.0",
+    "@intentic/extension-manifest": "1.339.0",
+    "@intentic/registry": "1.339.0",
     "@orpc/contract": "1.15.4",
     "tslib": "2.8.1",
     "zod": "4.6.5"

package/src/chores/probes.ts

@@ -1,3 +1,5 @@
+import { parseJsonOr } from "@intentic/base/json";
+import { isRecord } from "@intentic/base/escape";
 import type { Advisory, Bundle, DeadCode, Duplication, MutationScore, OutdatedPackage, ProbeFacts, ProbeId, UiScan } from "../schemas/maintenance.js";
 import type { IdiomRule } from "./stack.js";
 import {
@@ -46,12 +48,8 @@ const asObject = (text: string): Record<string, unknown> | undefined => {
     if (start === -1) {
         return undefined;
     }
-    try {
-        const parsed: unknown = JSON.parse(text.slice(start));
-        return typeof parsed === `object` && parsed !== null && !Array.isArray(parsed) ? (parsed as Record<string, unknown>) : undefined;
-    } catch {
-        return undefined;
-    }
+    const parsed = parseJsonOr(text.slice(start), undefined);
+    return isRecord(parsed) ? parsed : undefined;
 };
 
 const asString = (value: unknown): string | undefined => (typeof value === `string` && value !== `` ? value : undefined);

package/src/contracts/agents.contract.ts

@@ -1,3 +1,4 @@
+import { z } from "zod";
 import { procedure } from "../protocol/route-meta.js";
 import { AgentToolChildrenSchema, AgentTranscriptSchema, SessionTranscriptSchema } from "../events/transcript.js";
 import {
@@ -25,7 +26,7 @@ import {
     AgentUnsentSchema,
     LandResultSchema,
 } from "../schemas/agents.js";
-import { AgentsListSchema } from "../schemas/agents-list.js";
+import { AgentsAttentionSchema, AgentsListSchema } from "../schemas/agents-list.js";
 import { AgentChangesSchema, AgentConflictsSchema, AgentIgnoredSchema, AgentScratchSchema, AgentHistorySchema } from "../schemas/git/git.js";
 import { FileDiffSchema } from "../schemas/history.js";
 import { OkSchema } from "../schemas/shared.js";
@@ -36,6 +37,10 @@ import { ConversationPromptSchema } from "../schemas/system-prompt.js";
 // `archive` is the non-destructive counterpart to `discard` (worktree committed, entry kept); `purge` is `discard`
 // applied to every already-archived agent.
 export const agentsContract = {
+    // The documents a conversation's calls recorded writing (producedDocumentPaths), which its owner may take as bytes at
+    // GET /agents/{id}/documents/raw; a guest's too, since a guest has no Files to find them in.
+    documents: procedure.route({ method: "GET", path: "/agents/{id}/documents", summary: "Recorded result documents" })
+        .meta({ guest: true }).input(AgentIdSchema).output(z.object({ paths: z.array(z.string()) })),
     list: procedure
         .route({
             method: "GET",
@@ -46,6 +51,18 @@ export const agentsContract = {
         })
         .meta({ guest: true })
         .output(AgentsListSchema),
+    // The owner's only, and never a program's or a panel's: it is how the machine that runs the sandbox reads it with a
+    // session it minted for the owner (`ic sandbox attention`), and a member's count would not be the owner's anyway.
+    attention: procedure
+        .route({
+            method: "GET",
+            path: "/agents/attention",
+            summary: "What needs you, and what is working",
+            description:
+                "Two counts over the live fleet, by the board's own rules: the cards in its Attention lane plus the automations waiting for a yes, and the conversations producing something right now. What a status bar shows without reading the whole fleet.",
+        })
+        .meta({ floor: "owner", control: "never", panel: false })
+        .output(AgentsAttentionSchema),
     archived: procedure
         .route({
             method: "GET",

package/src/contracts/capabilities.contract.ts

@@ -9,6 +9,7 @@ import {
     CapabilityLoginSchema,
     CapabilityOtpSchema,
     CapabilityProbeSchema,
+    CapabilityRefreshTokenInputSchema,
     CapabilityRenameSchema,
     CapabilitySchema,
     CapabilitySecretInputSchema,
@@ -99,6 +100,19 @@ export const capabilitiesContract = {
         })
         .input(CapabilitySecretInputSchema)
         .output(OkSchema),
+    // Called by a connector's own CLI and listener process, never by a page: a sign-in on the agent's side stores its
+    // refresh token here rather than printing it for someone to paste.
+    oauthToken: capabilityRoute
+        .route({
+            method: "POST",
+            path: "/capabilities/{id}/oauth-token",
+            summary: "Store a delegated sign-in's refresh token",
+            description:
+                "Write-only. Only for a card whose manifest declares `refreshToken`, only with the card's current token in hand, and only while the card still holds the settings the sign-in was made against. Never returns a token or changes any other setting.",
+        })
+        .meta({ agent: true, panel: false })
+        .input(CapabilityRefreshTokenInputSchema)
+        .output(OkSchema),
     status: capabilityRoute
         .route({
             method: "GET",

package/src/contracts/device.contract.ts

@@ -8,6 +8,22 @@ import { LoopbackCatchEventSchema, LoopbackCatchSchema } from "../schemas/loopba
 import { OkSchema } from "../schemas/shared.js";
 import { ProjectDeliveryResultSchema, ProjectDeliverySchema } from "../schemas/project-delivery.js";
 import { DialLoopbackSchema, StageArtifactResultSchema, StageArtifactSchema } from "../schemas/device-artifacts.js";
+import {
+    KeyringCopiesSchema,
+    KeyringInboxItemSchema,
+    KeyringInboxResultSchema,
+    KeyringReleaseResultSchema,
+    KeyringSharesSchema,
+    KeyringSyncDeliverResultSchema,
+    KeyringSyncDeliverSchema,
+    KeyringSyncOutboxSchema,
+    KeyringSyncPairResultSchema,
+    KeyringSyncPairSchema,
+    KeyringSyncStateSchema,
+    KeyringTypeInputSchema,
+    KeyringTypeResultSchema,
+    SignedKeyringGrantSchema,
+} from "../schemas/keyring.js";
 
 // What a connected device can be asked, over the socket it opened; the machine is the oRPC server, the daemon the
 // client. No `.route()`: the procedure path is the address, not HTTP. Every input is strict (devices.ts says why). `mcp` stays opaque (`z.unknown()`) so a machine
@@ -46,4 +62,18 @@ export const deviceContract = {
     // the connection, or throws (nothing listening there, the switch is off). Advertised with `programs`; the machine
     // allows it when "Run commands" or "Run programs this sandbox sends" is on, either of which already reaches it.
     dialLoopback: oc.input(DialLoopbackSchema).output(z.object({ ok: z.literal(true) })),
+    // The keyring on this computer (schemas/keyring.ts), relayed: the machine passes each call to intentic-keyring over its
+    // local pipe and carries the answer back, ciphertext both ways where a value rides. Only the daemon calls these,
+    // never a tool, so no turn can reach the keyring by naming a procedure; sent only to an agent advertising `keyring`.
+    // `keyringShares` answers for the asking sandbox alone: the machine names it from the link the call came in on.
+    keyringShares: oc.output(KeyringSharesSchema),
+    keyringRelease: oc.input(SignedKeyringGrantSchema).output(KeyringReleaseResultSchema),
+    keyringType: oc.input(KeyringTypeInputSchema).output(KeyringTypeResultSchema),
+    keyringInbox: oc.input(KeyringInboxItemSchema).output(KeyringInboxResultSchema),
+    keyringCopies: oc.output(KeyringCopiesSchema),
+    // Keeping two of the owner's keyrings in step through this sandbox, which carries only what is sealed between them.
+    keyringSyncState: oc.output(KeyringSyncStateSchema),
+    keyringSyncPair: oc.input(KeyringSyncPairSchema).output(KeyringSyncPairResultSchema),
+    keyringSyncOutbox: oc.output(KeyringSyncOutboxSchema),
+    keyringSyncDeliver: oc.input(KeyringSyncDeliverSchema).output(KeyringSyncDeliverResultSchema),
 };

package/src/contracts/org.contract.ts

@@ -0,0 +1,19 @@
+import { procedure } from "../protocol/route-meta.js";
+import { OrgPolicyStateSchema } from "../schemas/organisation.js";
+
+// The organisation this sandbox belongs to, as the daemon enforces it (docs/architecture/organisations.md). The
+// platform hands the policy over the sandbox's own connect token; this is the editor's read of the copy that decides,
+// so the hub hides and locks what the daemon will refuse rather than what the platform last said. A guest may read it:
+// it names the organisation and which sections are held, nothing about anyone.
+export const orgContract = {
+    policy: procedure
+        .route({
+            method: "GET",
+            path: "/org/policy",
+            summary: "Which organisation manages this sandbox, and what it holds",
+            description:
+                "Unbound for a personal sandbox. For one an organisation manages: its policy as this sandbox enforces it, section by section, and when that edition arrived.",
+        })
+        .meta({ guest: true })
+        .output(OrgPolicyStateSchema),
+};

package/src/contracts/privacy.contract.ts

@@ -8,6 +8,8 @@ import {
     PrivacyKnownSourceSchema,
     PrivacyKnownValueSchema,
     PrivacyLedgerEntrySchema,
+    PRIVACY_PREVIEW_MAX,
+    PrivacyPreviewSchema,
     PrivacyRevealSchema,
     PrivacyShieldPolicySchema,
     PrivacyShieldStatusSchema,
@@ -76,11 +78,21 @@ export const privacyContract = {
             path: "/privacy/dictionary",
             summary: "The name lists the shield finds names by",
             description:
-                "Every list the dictionary holds (first names, surnames, words that are names only beside other evidence, titles), how many words each has and where they come from. With a query, what the dictionary makes of it as a name, and for one word the listed words starting with it.",
+                "Every list the dictionary holds (first names, surnames, words that are names only beside other evidence, titles), the owner's own lists among them, whether each is switched on, how many words each has and where they come from. With a query, what the dictionary as the owner set it makes of it as a name, and for one word the listed words starting with it.",
         })
         .meta({ agent: true })
         .input(z.object({ query: z.string().max(100).optional().describe("A word, the start of one, or a full name.") }))
         .output(PrivacyDictionarySchema),
+    preview: procedure
+        .route({
+            method: "POST",
+            path: "/privacy/preview",
+            summary: "Try the shield on a text",
+            description:
+                "What the shield would mask in the text with the policy as saved (every detector, the name lists, the owner's own rules, the values the vault knows) and what found each. Nothing is given a token or kept, whatever the switch says.",
+        })
+        .input(z.object({ text: z.string().max(PRIVACY_PREVIEW_MAX) }))
+        .output(PrivacyPreviewSchema),
     sources: procedure
         .route({
             method: "GET",

package/src/contracts/secrets.contract.ts

@@ -15,6 +15,14 @@ import {
     SecretHostGuardSetSchema,
     SecretHostGuardsSchema,
     SecretKeysSchema,
+    SecretProgramGuardSetResultSchema,
+    SecretProgramGuardSetSchema,
+    SecretProgramGuardsSchema,
+    SecretTypeIntoResultSchema,
+    SecretTypeIntoSchema,
+    SandboxKeyringPairResultSchema,
+    SandboxKeyringPairSchema,
+    SandboxKeyringsSchema,
     SecretRevealSchema,
     SecretSetSchema,
 } from "../schemas/secrets.js";
@@ -143,6 +151,62 @@ export const secretsContract = {
         .meta({ agent: true })
         .input(SecretHostGuardSetSchema)
         .output(SecretHostGuardSetResultSchema),
+    // The program guard, the host guard's counterpart for typing into windows on the owner's computers (schemas/secrets.ts
+    // SecretProgramsSchema): read by the agent so a use aims where it may go; narrowing is anybody's, widening the owner's.
+    programs: secretRoute
+        .route({
+            method: "GET",
+            path: "/secrets/programs",
+            summary: "Which programs each secret may be typed into",
+            description:
+                "Every sandbox-held secret whose program list is set: the programs on the owner's computers and the phone apps it goes into unasked. A secret held in a computer's keyring carries its own list, shown on its inventory row. Names and programs only, never values.",
+        })
+        .meta({ agent: true })
+        .output(SecretProgramGuardsSchema),
+    setPrograms: secretRoute
+        .route({
+            method: "PUT",
+            path: "/secrets/programs/{subject}",
+            summary: "Set which programs a secret may be typed into",
+            description:
+                "Replaces one sandbox-held secret's program list. Taking programs away, or turning `anyField` off, is open to anybody who may use secrets; adding one is the owner's: from the agent it raises a card for the owner in the live conversation and waits. Refused for a secret a computer's keyring holds, whose list is changed on that computer.",
+        })
+        .meta({ agent: true })
+        .input(SecretProgramGuardSetSchema)
+        .output(SecretProgramGuardSetResultSchema),
+    // The owner's own Type into…, never the agent's: it types into whatever has focus, which only a person at that
+    // computer can aim.
+    typeInto: secretRoute
+        .route({
+            method: "POST",
+            path: "/secrets/type-into",
+            summary: "Type a secret into the focused window on one of your computers",
+            description:
+                "After a short countdown, types one secret into whatever has focus on the computer named, through its keyring, which checks the window and still asks there when the entry's share says to. Answers what it went into, never the value.",
+        })
+        .meta({ panel: false })
+        .input(SecretTypeIntoSchema)
+        .output(SecretTypeIntoResultSchema),
+    keyrings: secretRoute
+        .route({
+            method: "GET",
+            path: "/secrets/keyrings",
+            summary: "The keyrings on your computers",
+            description:
+                "Every connected computer with a keyring this sandbox can reach: whether it answers and is unlocked, how many of its entries are shared here, and whom it is paired with. Names and counts only, never values.",
+        })
+        .output(SandboxKeyringsSchema),
+    keyringPair: secretRoute
+        .route({
+            method: "POST",
+            path: "/secrets/keyrings/pair",
+            summary: "Pair the keyrings on two of your computers",
+            description:
+                "Asks each computer's keyring to pair with the other: each shows a prompt with both fingerprints, and only a yes on both pairs them. After that each keeps the other's entries in step, sealed between them and carried by this sandbox, which cannot open what it carries.",
+        })
+        .meta({ panel: false })
+        .input(SandboxKeyringPairSchema)
+        .output(SandboxKeyringPairResultSchema),
     // The credential gateway's say over one connection: how its credential reaches the agent, and what it may do there.
     policy: secretRoute
         .route({

package/src/events/requests.ts

@@ -68,7 +68,9 @@ export const ChildAgentAskSchema = ChildRunSchema.extend({
     message: z
         .string()
         .optional()
-        .describe("What the parent would say to it: the message it sends, or the answers it gives. Clipped for the request."),
+        .describe(
+            "What the parent would say to it: the prompt a described start opens on, the message it sends, or the answers it gives. Clipped for the request, with an ellipsis where it was cut.",
+        ),
     on: z.string().optional().describe('Which machine it runs on, when one is named: a runner, or "here" for this sandbox.'),
     proposed: ChildRunSchema.optional().describe(
         "What the agent asked to start it on, when the owner started it on something else instead. Present only once the request has settled that way.",

package/src/events/system-events.ts

@@ -51,6 +51,15 @@ export const HelloSchema = z.object({
     workspaceId: z.string(),
     routes: z.array(z.string()).optional(),
     shapes: z.record(z.string(), z.string()).optional(),
+    // The same two for the hand-written routes (`POST /workspace/upload-diff`), which are half the daemon's surface and
+    // used to be advertised nowhere: a call onto a raw route an older daemon predates could only come back as a bare
+    // 404. Their own fields rather than more entries in `routes`, which an older browser reads as proof that it is
+    // itself the stale side. Absent means a daemon from before this field, and no evidence either way.
+    // `rawFingerprints` is what `shapes` is for a procedure, under the name the rest of the code gives it.
+    rawRoutes: z.array(z.string()).optional(),
+    rawFingerprints: z.record(z.string(), z.string()).optional(),
+    // `<version>:<newest mtime of the compiled tree>`, as every release since 1.0.0 sends it. The version at its head
+    // is what the browser holds against the oldest daemon it supports (state/daemon-floor.ts), so it stays first.
     build: z.string().optional(),
     boot: BootProgressSchema.optional(),
     // A project sandbox's folder, workspace-relative (`my-app` for /work/my-app): the owner's own folder, synced live