toolroll 0.9.84 → 0.9.85

package/dist/chat-review.d.ts

@@ -1,5 +1,6 @@
 import type { Store } from "./store.js";
 import type { VerifiedApprover } from "./principal.js";
+import { type FeedbackImage } from "./result-review.js";
 export type ReviewSnapshot = {
     task: string;
     root: string;
@@ -9,11 +10,13 @@ export type ReviewSnapshot = {
     sha: string;
     source: string;
     title: string;
+    images?: FeedbackImage[];
     notes: {
         id: number;
         note: string;
         path: string | null;
         line: number | null;
+        image?: FeedbackImage | null;
     }[];
 };
 type Problem = {
@@ -32,6 +35,7 @@ export type ReviewRequest = {
     path: string | null;
     line: number | null;
     notes: number[];
+    image?: FeedbackImage | null;
 };
 export declare function reviewInputProblem(note: string | null, path: string | null, line: number | null): string | null;
 /** Chat and the result form write the same comments and call the same revision service.

package/dist/chat-review.js

@@ -1,7 +1,8 @@
+import { selectResultImages } from "./chat-evidence.js";
 import { readVerifiedArtifact } from "./evidence.js";
 import { hasForbiddenControls, validateNote } from "./decision.js";
-import { isRevisionFeedback, revisionSourceOf } from "./result-review.js";
-import { createResultRevision } from "./result-actions.js";
+import { parseFeedbackImage, isRevisionFeedback, revisionSourceOf } from "./result-review.js";
+import { createResultRevision, feedbackImageProblem } from "./result-actions.js";
 /** Read precisely the result named, never silently substitute a newer version. */
 export function readChatResult(store, who, evidenceRoot, task, run) {
     const ref = store.lookupRef(task);
@@ -21,11 +22,13 @@ export function readChatResult(store, who, evidenceRoot, task, run) {
     const proven = readVerifiedArtifact(evidenceRoot, artifact);
     if (!proven.ok)
         return { ok: false, message: "The saved changes could not be verified. Restore the result before adding feedback." };
+    const images = selectResultImages(store, who, evidenceRoot, task, found.id);
     return { ok: true, snapshot: {
             task, root: family.root.id, execution: family.current.id, run: found.id,
             artifact: artifact.id, sha: artifact.sha256, source: revisionSourceOf(store.getScope(task)?.digest ?? null),
             title: store.getTask(task)?.title ?? task,
-            notes: store.liveDiffComments(found.id).filter(isRevisionFeedback).map(one => ({ id: one.id, note: one.note, path: one.path, line: one.line })),
+            images: images.ok ? images.selection.images.map(one => ({ run: found.id, artifact: one.artifact, sha256: one.sha256 })) : [],
+            notes: store.liveDiffComments(found.id).filter(isRevisionFeedback).map(one => ({ id: one.id, note: one.note, path: one.path, line: one.line, image: one.image ?? null })),
         } };
 }
 export function reviewInputProblem(note, path, line) {
@@ -65,9 +68,15 @@ export function applyChatReview(store, who, evidenceRoot, request, now, allowMod
                 return fail("Some feedback changed or was already used. Review it again.");
             if (operation === "note" && (note === null || notes.length > 0))
                 return fail("A saved note needs feedback text and cannot consume other notes.");
+            const image = parseFeedbackImage(request.image);
+            if (image === false || (image !== null && note === null))
+                return fail("Choose a screenshot and write its feedback again.");
+            const imageProblem = feedbackImageProblem(store, evidenceRoot, live.run, image);
+            if (imageProblem !== null)
+                return fail(imageProblem);
             const batch = [...notes].sort((a, b) => a - b);
             if (note !== null) {
-                const id = store.addDiffComment({ artifactId: live.artifact, runId: live.run, path, line, note, author: who.name }, now);
+                const id = store.addDiffComment({ artifactId: live.artifact, runId: live.run, path, line, note, author: who.name, image }, now);
                 if (id === null)
                     return fail("The note could not be saved.");
                 batch.push(id);

package/dist/chat-terms.d.ts

@@ -0,0 +1,9 @@
+import type { Scope } from "./scope.js";
+/** What a plan's yes allows an agent to do, in a few plain words (the approval sheet's "You're allowing"). */
+export declare function permissionPlainWords(profile: Scope["profile"] | null | undefined): string | null;
+export type ShownScope = Pick<Scope, "goal" | "outOfScope" | "touches" | "acceptance" | "profile" | "budgetMicrousd">;
+/** Every word of the terms a yes agrees to, as the card shows them: the goal, what's excluded, the files (or plainly any
+ * file), each requirement with the evidence it needs, and what the agent may do and spend. Nothing is shortened. */
+export declare function scopeTermsText(scope: ShownScope): string;
+/** The digest of the terms shown, bound to the scope's own digest: a changed word, limit or route is another digest. */
+export declare function shownTermsDigest(scope: ShownScope & Pick<Scope, "digest">): string;

package/dist/chat-terms.js

@@ -0,0 +1,46 @@
+/**
+ * A scope's terms as a chat card shows them whole, and the digest of exactly those words. A task filed from outside
+ * text (a youiyoux change request) approves from chat only on a card that showed every word of its terms, nothing cut:
+ * the card binds that digest to its button, and the seal (store.ts, the outside-request quarantine) recomputes it from
+ * the live scope and refuses a tap that names anything else. A leaf: the store and the chat road both read it.
+ */
+import { createHash } from "node:crypto";
+import { isAcpProfile } from "./acp-agents.js";
+/** What a plan's yes allows an agent to do, in a few plain words (the approval sheet's "You're allowing"). */
+export function permissionPlainWords(profile) {
+    if (profile === null || profile === undefined)
+        return null;
+    const full = "full access, nothing asks first";
+    if (profile.provider === "claude") {
+        return profile.permissionArgv === "bypassPermissions" ? full
+            : profile.permissionArgv === "auto" ? "file edits and routine commands; anything risky stops"
+                : "file edits only; commands are refused";
+    }
+    if (profile.provider === "gemini")
+        return profile.approvalArgv === "yolo" ? full : "file edits only; other tools are refused";
+    if (isAcpProfile(profile))
+        return "full access inside the OS fence, nothing asks first";
+    return profile.sandboxMode === "danger-full-access" ? full : "file edits and commands inside the project only";
+}
+const money = (micro) => `$${(micro / 1_000_000).toFixed(2)}`;
+/** Every word of the terms a yes agrees to, as the card shows them: the goal, what's excluded, the files (or plainly any
+ * file), each requirement with the evidence it needs, and what the agent may do and spend. Nothing is shortened. */
+export function scopeTermsText(scope) {
+    const allows = [permissionPlainWords(scope.profile) ?? "agent permissions not known", scope.budgetMicrousd === null ? "no attempt limit" : `up to ${money(scope.budgetMicrousd)} per attempt`];
+    return [
+        "Goal:", scope.goal,
+        "",
+        "Not this:", scope.outOfScope ?? "Nothing excluded.",
+        "",
+        `Files: ${scope.touches.length === 0 ? "any file (no file list)" : scope.touches.join(", ")}`,
+        "",
+        "Done when:",
+        ...(scope.acceptance.length === 0 ? ["You decide when you review the result."] : scope.acceptance.map(one => `• ${one.statement} (${one.evidence.join(", ")})`)),
+        "",
+        `Starting allows: ${allows.join(" · ")}`,
+    ].join("\n");
+}
+/** The digest of the terms shown, bound to the scope's own digest: a changed word, limit or route is another digest. */
+export function shownTermsDigest(scope) {
+    return createHash("sha256").update(JSON.stringify({ v: 1, scope: scope.digest, shown: scopeTermsText(scope) })).digest("hex");
+}

package/dist/contracts/console-api.d.ts

@@ -102,6 +102,7 @@ export declare const CONSOLE_FORMS: {
     readonly data: FormContract<"password">;
     readonly flowsOn: FormContract<"repo" | "starter">;
     readonly integrationsTest: FormContract<"key">;
+    readonly integrationsYouiyoux: FormContract<"on" | "repo">;
     readonly monitoring: FormContract<"folder" | "header-name" | "header-value" | "password" | "rotate" | "traces" | "webhook">;
     readonly toolsConnect: FormContract<"access" | "also" | "kit" | "password" | "repo" | "service" | "shown" | "template">;
     readonly toolsChange: FormContract<"action" | "catalog" | "import" | "name" | "password" | "repo" | "secret" | "secrets" | "shown" | "target" | "transport" | "value">;
@@ -168,7 +169,7 @@ export declare const CONSOLE_FORMS: {
     readonly chatAck: FormContract<"nonce" | "token">;
     readonly recipes: FormContract<"document" | "next" | "preview" | "projectRevision" | "purpose" | "recipe" | "recipeRevision" | "repo" | "source" | "sourceRevision">;
     readonly runNote: FormContract<"note">;
-    readonly diffComment: FormContract<"batch" | "intent" | "line" | "note" | "path" | "request" | "return" | "source" | "tab">;
+    readonly diffComment: FormContract<"batch" | "comment" | "image" | "intent" | "line" | "note" | "path" | "request" | "return" | "source" | "tab">;
     readonly editorLinks: FormContract<"on" | "return">;
     readonly revise: FormContract<"batch" | "return" | "source">;
     readonly followUp: FormContract<"level" | "return">;

package/dist/contracts/console-api.js

@@ -111,6 +111,7 @@ export const CONSOLE_FORMS = {
     data: formContract("POST /settings/data", ["password"]),
     flowsOn: formContract("POST /settings/flows/on", ["repo", "starter"]),
     integrationsTest: formContract("POST /settings/integrations/test", ["key"]),
+    integrationsYouiyoux: formContract("POST /settings/integrations/youiyoux", ["repo", "on"]),
     monitoring: formContract("POST /settings/monitoring", ["password", "webhook", "folder", "traces", "header-name", "header-value", "rotate"]),
     toolsConnect: formContract("POST /settings/tools/connect", ["repo", "also", "service", "template", "kit", "shown", "password", "access"]),
     toolsChange: formContract("POST /settings/tools/change", ["repo", "shown", "action", "name", "password", "catalog", "transport", "target", "secrets", "import", "secret", "value"]),
@@ -182,7 +183,7 @@ export const CONSOLE_FORMS = {
     // A recipe's own answers and editor fields are read by recipes.ts from the whole form (`sent`; item 17).
     recipes: formContract("POST /recipes/prepare, /recipes/preview, /recipes/import, /recipes/launch, /recipes/save", ["repo", "projectRevision", "recipe", "recipeRevision", "document", "purpose", "source", "sourceRevision", "preview", "next"]),
     runNote: formContract("POST /r/<run>/note", ["note"]),
-    diffComment: formContract("POST /r/<run>/comment", ["return", "tab", "intent", "batch", "source", "note", "path", "line", "request"]),
+    diffComment: formContract("POST /r/<run>/comment", ["return", "tab", "intent", "batch", "source", "note", "path", "line", "request", "image", "comment"]),
     editorLinks: formContract("POST /session/editor-links", ["on", "return"]),
     revise: formContract("POST /r/<run>/revise", ["return", "batch", "source"]),
     followUp: formContract("POST /r/<run>/checks|add-tests", ["return", "level"]),

package/dist/contracts/lead-tools.d.ts

@@ -36,6 +36,10 @@ export declare const LEAD_TOOL_INPUTS: {
     readonly get_brief: z.ZodObject<{
         repo: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
+    readonly get_project_activity: z.ZodObject<{
+        repo: z.ZodString;
+        offset: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
     readonly get_project_context: z.ZodObject<{
         repo: z.ZodString;
         query: z.ZodString;
@@ -130,6 +134,7 @@ export declare const LEAD_TOOL_INPUTS: {
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         line: z.ZodOptional<z.ZodNullable<z.ZodInt>>;
         saved_notes: z.ZodOptional<z.ZodArray<z.ZodInt>>;
+        image: z.ZodOptional<z.ZodNullable<z.ZodInt>>;
     }, z.core.$strict>;
     readonly recap: z.ZodObject<{
         since: z.ZodOptional<z.ZodString>;
@@ -762,6 +767,10 @@ export declare const LEAD_TOOL_READ_INPUTS: {
     readonly get_brief: z.ZodObject<{
         repo: z.ZodOptional<z.ZodString>;
     }, z.core.$strict>;
+    readonly get_project_activity: z.ZodObject<{
+        repo: z.ZodString;
+        offset: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strict>;
     readonly get_project_context: z.ZodObject<{
         repo: z.ZodString;
         query: z.ZodString;
@@ -856,6 +865,7 @@ export declare const LEAD_TOOL_READ_INPUTS: {
         path: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         line: z.ZodOptional<z.ZodNullable<z.ZodInt>>;
         saved_notes: z.ZodOptional<z.ZodArray<z.ZodInt>>;
+        image: z.ZodOptional<z.ZodNullable<z.ZodInt>>;
     }, z.core.$strict>;
     readonly recap: z.ZodObject<{
         since: z.ZodOptional<z.ZodString>;
@@ -1556,6 +1566,26 @@ export declare const LEAD_TOOL_OUTPUTS: {
         projects: z.ZodArray<z.ZodUnknown>;
         omissions: z.ZodObject<{}, z.core.$loose>;
     }, z.core.$loose>;
+    readonly get_project_activity: z.ZodObject<{
+        asOf: z.ZodString;
+        since: z.ZodString;
+        days: z.ZodNumber;
+        limit: z.ZodNumber;
+        truncated: z.ZodBoolean;
+        ready: z.ZodObject<{
+            count: z.ZodNumber;
+            oldestFinishedAgeMs: z.ZodNullable<z.ZodNumber>;
+            dated: z.ZodNumber;
+        }, z.core.$strip>;
+        completed: z.ZodObject<{
+            count: z.ZodNumber;
+        }, z.core.$loose>;
+        families: z.ZodArray<z.ZodUnknown>;
+        familiesTotal: z.ZodNumber;
+        familiesOffset: z.ZodNumber;
+        nextOffset: z.ZodNullable<z.ZodNumber>;
+        incompleteHistory: z.ZodNumber;
+    }, z.core.$loose>;
     readonly get_project_context: z.ZodObject<{
         version: z.ZodLiteral<1>;
         readOnly: z.ZodBoolean;

package/dist/contracts/lead-tools.js

@@ -52,6 +52,7 @@ export const LISTED_TASK_STATES = ["queued", "running", "done", "failed", "cance
 const ACTION_OPERATIONS = Object.keys(CHAT_ACTIONS).filter(one => !one.startsWith("flow_") && !one.startsWith("subagent_"));
 export const LEAD_TOOL_INPUTS = {
     get_brief: z.strictObject({ repo: repoId.optional() }),
+    get_project_activity: z.strictObject({ repo: repoId, offset: offset.optional() }),
     get_project_context: z.strictObject({ repo: repoId, query: text("contextQuery").min(1), mode: z.enum(["search", "impact"]).optional() }),
     get_action_status: z.strictObject({ proposal: id }),
     get_actions: z.strictObject({}),
@@ -77,6 +78,7 @@ export const LEAD_TOOL_INPUTS = {
         note: z.string().max(LIMITS.note).nullable().optional(), path: text("diffPath").nullable().optional(),
         line: z.int().min(1).max(1_000_000).nullable().optional(),
         saved_notes: z.array(id).max(100).optional(),
+        image: id.nullable().optional().describe("Screenshot artifact id from get_result_images; attaches the exact verified image to this feedback. null leaves off the screenshot a reply targets."),
     }),
     recap: z.strictObject({ since: text("recapSince").optional() }),
     list_repos: z.strictObject({}),
@@ -196,6 +198,7 @@ export const decisionOutput = z.looseObject({ repo: str, decision: int, task: st
 export const queueColumnsOutput = { columns: rows({ column: str, tasks: list }) };
 export const LEAD_TOOL_OUTPUTS = {
     get_brief: catchUpOutput,
+    get_project_activity: z.looseObject({ asOf: str, since: str, days: int, limit: int, truncated: z.boolean(), ready: z.object({ count: int, oldestFinishedAgeMs: nullable(int), dated: int }), completed: z.looseObject({ count: int }), families: list, familiesTotal: int, familiesOffset: int, nextOffset: nullable(int), incompleteHistory: int }),
     get_project_context: repositoryContextOutput,
     get_action_status: z.looseObject({ proposal: int, operation: str, state: str, outcome: z.unknown(), finishedAt: nullable(str) }),
     get_actions: z.looseObject({ actions: rows({ operation: str, label: str, secureReview: z.boolean(), inputs: z.array(str) }), notice: str }),

package/dist/contracts/youiyoux-request.d.ts

@@ -0,0 +1,248 @@
+/**
+ * A youiyoux request as Toolroll reads it (youiyoux-intake.ts): the published `youi.request/v1` schema (youiyoux's
+ * schema/youi.request.schema.json), held to its own limits, and the `youi.proposal/v1` options file an options request's
+ * agent writes (schema/youi.proposal.schema.json). Unknown keys are allowed, as the published schemas allow them;
+ * everything Toolroll reads is checked here, and every string is outside text all the same.
+ */
+import { z } from "zod";
+import { type ContractResult } from "./contract.js";
+export declare const REQUEST_ID: RegExp;
+/** An options file's id: `p-` and the same 10 hex as the options request it answers. */
+export declare const PROPOSAL_ID: RegExp;
+/** The provenance every task filed from a request carries (task_ref.filed_via): immutable, and the seal reads it. */
+export declare const YOUIYOUX_FILED_VIA = "youiyoux";
+/** The one chat card a pass's filings make for a project (youiyoux-intake.ts), drawn by chat-decide.ts: the new tasks,
+ * Approve all and each one's own Approve and Open. */
+export declare const YOUIYOUX_CARD_KIND = "youiyoux-requests";
+/** Where a person sees and approves everything waiting on them in the console (flow-triggers.ts NEEDS_YOU_HREF). */
+export declare const YOUIYOUX_HOME_PATH = "/work?view=needs-you";
+export declare const YOUIYOUX_EVIDENCE: readonly ["screenshot", "check", "changed-path", "manual-review"];
+/** What an options request offers its agent: the one file to write (`.youi/proposals/<proposal>.json`), the props an
+ * option may set (enum values from `values`), and whether it may give the component new text. */
+export declare const youiyouxOfferSchema: z.ZodObject<{
+    proposal: z.ZodString;
+    file: z.ZodString;
+    choices: z.ZodRecord<z.ZodString, z.ZodObject<{
+        type: z.ZodEnum<{
+            boolean: "boolean";
+            enum: "enum";
+            number: "number";
+            string: "string";
+        }>;
+        values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+    }, z.core.$strip>>;
+    text: z.ZodBoolean;
+}, z.core.$strip>;
+export type YouiyouxOffer = z.infer<typeof youiyouxOfferSchema>;
+export declare const youiyouxTaskSchema: z.ZodObject<{
+    title: z.ZodString;
+    goal: z.ZodString;
+    touches: z.ZodArray<z.ZodString>;
+    touchesKnown: z.ZodBoolean;
+    why: z.ZodOptional<z.ZodString>;
+    not: z.ZodArray<z.ZodString>;
+    acceptance: z.ZodArray<z.ZodObject<{
+        statement: z.ZodString;
+        evidence: z.ZodArray<z.ZodEnum<{
+            "changed-path": "changed-path";
+            check: "check";
+            "manual-review": "manual-review";
+            screenshot: "screenshot";
+        }>>;
+    }, z.core.$strip>>;
+    offer: z.ZodOptional<z.ZodObject<{
+        proposal: z.ZodString;
+        file: z.ZodString;
+        choices: z.ZodRecord<z.ZodString, z.ZodObject<{
+            type: z.ZodEnum<{
+                boolean: "boolean";
+                enum: "enum";
+                number: "number";
+                string: "string";
+            }>;
+            values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+        }, z.core.$strip>>;
+        text: z.ZodBoolean;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const youiyouxRequestSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"youi.request/v1">;
+    id: z.ZodString;
+    project: z.ZodString;
+    kind: z.ZodEnum<{
+        change: "change";
+        comment: "comment";
+        options: "options";
+    }>;
+    status: z.ZodEnum<{
+        addressed: "addressed";
+        closed: "closed";
+        open: "open";
+    }>;
+    body: z.ZodString;
+    author: z.ZodObject<{
+        kind: z.ZodEnum<{
+            agent: "agent";
+            person: "person";
+        }>;
+        name: z.ZodString;
+    }, z.core.$strip>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    target: z.ZodObject<{
+        route: z.ZodString;
+        scope: z.ZodEnum<{
+            element: "element";
+            here: "here";
+        }>;
+        name: z.ZodString;
+        file: z.ZodOptional<z.ZodString>;
+        line: z.ZodOptional<z.ZodInt>;
+    }, z.core.$strip>;
+    task: z.ZodOptional<z.ZodObject<{
+        title: z.ZodString;
+        goal: z.ZodString;
+        touches: z.ZodArray<z.ZodString>;
+        touchesKnown: z.ZodBoolean;
+        why: z.ZodOptional<z.ZodString>;
+        not: z.ZodArray<z.ZodString>;
+        acceptance: z.ZodArray<z.ZodObject<{
+            statement: z.ZodString;
+            evidence: z.ZodArray<z.ZodEnum<{
+                "changed-path": "changed-path";
+                check: "check";
+                "manual-review": "manual-review";
+                screenshot: "screenshot";
+            }>>;
+        }, z.core.$strip>>;
+        offer: z.ZodOptional<z.ZodObject<{
+            proposal: z.ZodString;
+            file: z.ZodString;
+            choices: z.ZodRecord<z.ZodString, z.ZodObject<{
+                type: z.ZodEnum<{
+                    boolean: "boolean";
+                    enum: "enum";
+                    number: "number";
+                    string: "string";
+                }>;
+                values: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                default: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>;
+            }, z.core.$strip>>;
+            text: z.ZodBoolean;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    thread: z.ZodArray<z.ZodUnknown>;
+}, z.core.$strip>;
+export type YouiyouxRequest = z.infer<typeof youiyouxRequestSchema>;
+export type YouiyouxTask = z.infer<typeof youiyouxTaskSchema>;
+export declare function readYouiyouxRequest(raw: unknown): ContractResult<YouiyouxRequest>;
+/** The one file an options request's agent may write: `.youi/proposals/p-<the request's hex>.json`. */
+export declare const proposalIdOf: (request: string) => string;
+export declare const proposalFileOf: (proposal: string) => string;
+/** Why an options request can't be filed as youiyoux's contract has it, or null: it carries a task with an offer whose
+ * proposal is `p-<its own hex>`, whose file is that proposal's, and the task may touch that one file and nothing else. */
+export declare function optionsProblem(request: YouiyouxRequest): string | null;
+export declare const PROPOSAL_STATUSES: readonly ["open", "chosen", "dismissed"];
+export declare const youiyouxProposalSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    schema: z.ZodLiteral<"youi.proposal/v1">;
+    id: z.ZodString;
+    project: z.ZodString;
+    route: z.ZodString;
+    target: z.ZodObject<{
+        name: z.ZodString;
+        element: z.ZodOptional<z.ZodString>;
+        file: z.ZodOptional<z.ZodString>;
+        line: z.ZodOptional<z.ZodInt>;
+        column: z.ZodOptional<z.ZodInt>;
+        box: z.ZodObject<{
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>;
+        page: z.ZodOptional<z.ZodObject<{
+            width: z.ZodNumber;
+            height: z.ZodNumber;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    ask: z.ZodString;
+    author: z.ZodObject<{
+        kind: z.ZodEnum<{
+            agent: "agent";
+            person: "person";
+        }>;
+        name: z.ZodString;
+    }, z.core.$strip>;
+    createdAt: z.ZodString;
+    updatedAt: z.ZodString;
+    options: z.ZodArray<z.ZodObject<{
+        id: z.ZodEnum<{
+            a: "a";
+            b: "b";
+            c: "c";
+            d: "d";
+        }>;
+        label: z.ZodString;
+        why: z.ZodString;
+        set: z.ZodArray<z.ZodObject<{
+            prop: z.ZodString;
+            value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
+        }, z.core.$strip>>;
+        text: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    status: z.ZodEnum<{
+        chosen: "chosen";
+        dismissed: "dismissed";
+        open: "open";
+    }>;
+    choice: z.ZodOptional<z.ZodEnum<{
+        a: "a";
+        b: "b";
+        c: "c";
+        d: "d";
+    }>>;
+    decidedBy: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            agent: "agent";
+            person: "person";
+        }>;
+        name: z.ZodString;
+    }, z.core.$strip>>;
+    decidedAt: z.ZodOptional<z.ZodString>;
+    request: z.ZodOptional<z.ZodString>;
+    for: z.ZodString;
+}, z.core.$strip>;
+export type YouiyouxProposal = z.infer<typeof youiyouxProposalSchema>;
+export declare function readYouiyouxProposal(raw: unknown): ContractResult<YouiyouxProposal>;
+/** What Toolroll writes beside a request (`youi.request-task/v1`): the task it became, how that task stands, and, when
+ * the console has an address, the task's link and `home`, where a person sees and approves all waiting work. */
+export declare const YOUIYOUX_TASK_STATUSES: readonly ["queued", "needs-you", "building", "ready", "done", "failed", "stopped"];
+export type YouiyouxTaskStatus = (typeof YOUIYOUX_TASK_STATUSES)[number];
+/** A link youiyoux opens: http or https, at most 2,000 characters, with no user name or password in it. */
+export declare const youiyouxLinkSchema: z.ZodString;
+export declare const youiyouxRequestTaskSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"youi.request-task/v1">;
+    request: z.ZodString;
+    runner: z.ZodLiteral<"Toolroll">;
+    task: z.ZodObject<{
+        id: z.ZodString;
+        url: z.ZodNullable<z.ZodString>;
+    }, z.core.$strict>;
+    home: z.ZodOptional<z.ZodString>;
+    status: z.ZodEnum<{
+        building: "building";
+        done: "done";
+        failed: "failed";
+        "needs-you": "needs-you";
+        queued: "queued";
+        ready: "ready";
+        stopped: "stopped";
+    }>;
+    detail: z.ZodString;
+    updatedAt: z.ZodString;
+}, z.core.$strict>;
+export type YouiyouxRequestTask = z.infer<typeof youiyouxRequestTaskSchema>;
+export declare function readYouiyouxRequestTask(raw: unknown): ContractResult<YouiyouxRequestTask>;

package/dist/contracts/youiyoux-request.js

@@ -0,0 +1,152 @@
+/**
+ * A youiyoux request as Toolroll reads it (youiyoux-intake.ts): the published `youi.request/v1` schema (youiyoux's
+ * schema/youi.request.schema.json), held to its own limits, and the `youi.proposal/v1` options file an options request's
+ * agent writes (schema/youi.proposal.schema.json). Unknown keys are allowed, as the published schemas allow them;
+ * everything Toolroll reads is checked here, and every string is outside text all the same.
+ */
+import { z } from "zod";
+import { parseContract } from "./contract.js";
+export const REQUEST_ID = /^r-[0-9a-f]{10}$/;
+/** An options file's id: `p-` and the same 10 hex as the options request it answers. */
+export const PROPOSAL_ID = /^p-[0-9a-f]{10}$/;
+/** The provenance every task filed from a request carries (task_ref.filed_via): immutable, and the seal reads it. */
+export const YOUIYOUX_FILED_VIA = "youiyoux";
+/** The one chat card a pass's filings make for a project (youiyoux-intake.ts), drawn by chat-decide.ts: the new tasks,
+ * Approve all and each one's own Approve and Open. */
+export const YOUIYOUX_CARD_KIND = "youiyoux-requests";
+/** Where a person sees and approves everything waiting on them in the console (flow-triggers.ts NEEDS_YOU_HREF). */
+export const YOUIYOUX_HOME_PATH = "/work?view=needs-you";
+const text = (max) => z.string().min(1).max(max);
+const who = z.object({ kind: z.enum(["person", "agent"]), name: text(100) });
+// The published schema's date-time: an ISO timestamp with a zone.
+const when = z.string().max(40).regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/);
+export const YOUIYOUX_EVIDENCE = ["screenshot", "check", "changed-path", "manual-review"];
+/** A component prop as youiyoux names one: what an option may set. */
+const PROP = /^[A-Za-z_$][\w$]{0,63}$/;
+const value = z.union([z.string().max(2000), z.number().finite(), z.boolean()]);
+/** What an options request offers its agent: the one file to write (`.youi/proposals/<proposal>.json`), the props an
+ * option may set (enum values from `values`), and whether it may give the component new text. */
+export const youiyouxOfferSchema = z.object({
+    proposal: z.string().regex(PROPOSAL_ID),
+    file: text(500),
+    choices: z.record(z.string().regex(PROP), z.object({
+        type: z.enum(["enum", "string", "boolean", "number"]),
+        values: z.array(text(200)).max(100).optional(),
+        default: value.optional(),
+    })).refine(choices => Object.keys(choices).length <= 50, "at most 50 props"),
+    text: z.boolean(),
+});
+export const youiyouxTaskSchema = z.object({
+    title: text(120),
+    goal: text(4000),
+    touches: z.array(text(500)).max(50),
+    touchesKnown: z.boolean(),
+    why: text(500).optional(),
+    not: z.array(text(300)).max(10),
+    acceptance: z.array(z.object({ statement: text(300), evidence: z.array(z.enum(YOUIYOUX_EVIDENCE)).min(1) })).min(1).max(10),
+    /** An options request's: what its agent writes (optionsProblem holds it to the request). */
+    offer: youiyouxOfferSchema.optional(),
+});
+export const youiyouxRequestSchema = z.object({
+    schema: z.literal("youi.request/v1"),
+    id: z.string().regex(REQUEST_ID),
+    project: text(200),
+    kind: z.enum(["comment", "change", "options"]),
+    status: z.enum(["open", "addressed", "closed"]),
+    body: text(4000),
+    author: who,
+    createdAt: when,
+    updatedAt: when,
+    // Where the person pointed: the page, the component, and (when youiyoux knew it) the file and line that draw it.
+    target: z.object({ route: text(300), scope: z.enum(["here", "element"]), name: text(200), file: text(500).optional(), line: z.int().positive().max(Number.MAX_SAFE_INTEGER).optional() }),
+    task: youiyouxTaskSchema.optional(),
+    thread: z.array(z.unknown()).max(500),
+});
+export function readYouiyouxRequest(raw) {
+    return parseContract(youiyouxRequestSchema, raw);
+}
+/** The one file an options request's agent may write: `.youi/proposals/p-<the request's hex>.json`. */
+export const proposalIdOf = (request) => `p-${request.slice(2)}`;
+export const proposalFileOf = (proposal) => `.youi/proposals/${proposal}.json`;
+/** Why an options request can't be filed as youiyoux's contract has it, or null: it carries a task with an offer whose
+ * proposal is `p-<its own hex>`, whose file is that proposal's, and the task may touch that one file and nothing else. */
+export function optionsProblem(request) {
+    if (request.kind !== "options")
+        return null;
+    const offer = request.task?.offer;
+    if (request.task === undefined || offer === undefined)
+        return "it asks for options with no offer";
+    const proposal = proposalIdOf(request.id);
+    if (offer.proposal !== proposal)
+        return `its offer is for ${offer.proposal}, not ${proposal}`;
+    if (offer.file !== proposalFileOf(proposal))
+        return `its offer's file isn't ${proposalFileOf(proposal)}`;
+    if (!request.task.touchesKnown || request.task.touches.length !== 1 || request.task.touches[0] !== offer.file)
+        return "its task may touch more than its options file";
+    return null;
+}
+/** `youi.proposal/v1`: the options an agent puts on youiyoux's Screens canvas (youiyoux's packages/core/src/proposals.ts,
+ * mirrored). Toolroll checks only the shape and what it reads; youiyoux checks each option against the component's
+ * contract when it reads the file. */
+const OPTION_IDS = ["a", "b", "c", "d"];
+export const PROPOSAL_STATUSES = ["open", "chosen", "dismissed"];
+export const youiyouxProposalSchema = z.object({
+    $schema: z.string().max(500).optional(),
+    schema: z.literal("youi.proposal/v1"),
+    id: z.string().regex(PROPOSAL_ID),
+    project: text(200),
+    route: text(300),
+    target: z.object({
+        name: text(200), element: text(200).optional(), file: text(500).optional(),
+        line: z.int().positive().max(Number.MAX_SAFE_INTEGER).optional(), column: z.int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
+        box: z.object({ x: z.number().finite(), y: z.number().finite(), width: z.number().finite().nonnegative(), height: z.number().finite().nonnegative() }),
+        page: z.object({ width: z.number().finite().positive(), height: z.number().finite().positive() }).optional(),
+    }),
+    ask: text(1000),
+    author: who,
+    createdAt: when,
+    updatedAt: when,
+    options: z.array(z.object({
+        id: z.enum(OPTION_IDS),
+        label: text(60),
+        why: text(500),
+        set: z.array(z.object({ prop: z.string().regex(PROP), value })).max(20),
+        text: text(2000).nullable(),
+    }).refine(option => option.set.length > 0 || option.text !== null, "an option changes a prop or the text")).min(2).max(4),
+    status: z.enum(PROPOSAL_STATUSES),
+    choice: z.enum(OPTION_IDS).optional(),
+    decidedBy: who.optional(),
+    decidedAt: when.optional(),
+    request: z.string().regex(REQUEST_ID).optional(),
+    for: z.string().regex(REQUEST_ID),
+}).refine(doc => new Set(doc.options.map(option => option.id)).size === doc.options.length, "each option has its own letter")
+    .refine(doc => doc.choice === undefined || doc.options.some(option => option.id === doc.choice), "the choice is one of its options");
+export function readYouiyouxProposal(raw) {
+    return parseContract(youiyouxProposalSchema, raw);
+}
+/** What Toolroll writes beside a request (`youi.request-task/v1`): the task it became, how that task stands, and, when
+ * the console has an address, the task's link and `home`, where a person sees and approves all waiting work. */
+export const YOUIYOUX_TASK_STATUSES = ["queued", "needs-you", "building", "ready", "done", "failed", "stopped"];
+/** A link youiyoux opens: http or https, at most 2,000 characters, with no user name or password in it. */
+export const youiyouxLinkSchema = z.string().max(2000).refine(value => {
+    try {
+        const url = new URL(value);
+        return (url.protocol === "http:" || url.protocol === "https:") && url.username === "" && url.password === "";
+    }
+    catch {
+        return false;
+    }
+}, "an http or https address with no credentials");
+export const youiyouxRequestTaskSchema = z.strictObject({
+    schema: z.literal("youi.request-task/v1"),
+    request: z.string().regex(REQUEST_ID),
+    runner: z.literal("Toolroll"),
+    task: z.strictObject({ id: z.string().min(1).max(120), url: youiyouxLinkSchema.nullable() }),
+    home: youiyouxLinkSchema.optional(),
+    status: z.enum(YOUIYOUX_TASK_STATUSES),
+    detail: z.string().max(200),
+    updatedAt: when,
+});
+export function readYouiyouxRequestTask(raw) {
+    return parseContract(youiyouxRequestTaskSchema, raw);
+}