wicked-crew 0.16.11 → 0.16.13

package/dist/api/chat-context.d.ts

@@ -0,0 +1,236 @@
+/**
+ * THE CHAT SEES ARTIFACTS AND RUNS (DES-CHAT-ARTIFACTS-001 §5.1, §5.3; slice A1): the per-turn block crew adds to a
+ * chat message, built from crew's own reads.
+ *
+ * Studio sends `context` beside the person's words (`ChatMessageBody.context`): the artifact open on the surface the
+ * message came from (`<mount>/<doc>`, the version they are looking at, the parts they selected), the tab's appearance,
+ * and studio's page summary. Crew then, for every turn:
+ *
+ *  1. checks the SCOPE before anything is read or copied (the caller has already checked the chat's owner): a chat
+ *     filed in a project sees that project's documents and runs; any other chat sees what is on this daemon. What
+ *     fails is named in the block with its reason, never read. (DES §4.1 also lets a project chat read the Unfiled
+ *     documents it made; no chat makes documents before slice A3, which brings the durable per-document binding that
+ *     records it — so until then that exception has nothing to admit, and it is not inferred from run records.);
+ *  2. copies the viewed version and the latest into the chat's scratch root (`open/<mount>__<doc>-v<n>.html`): ids are
+ *     validated against their grammar, file names come from ids, the document directory must be a real directory
+ *     inside the project's docs root, each file is opened without following a link or blocking, capped, and written
+ *     exclusively read-only; a different content already under a copy's name is an error, never an overwrite;
+ *  3. writes a run brief (`context/run-<id>-<sha8>.md`, named by its content like the source packet's run briefs, so
+ *     a later turn's brief never replaces the bytes an earlier turn was given; `run-brief.ts`) for each run the person
+ *     names in this message: an id in their words that resolves on this daemon, a run chip, or the run page the chat
+ *     is on;
+ *  4. lists the ids the seat may use: recent turns, attachments, and the runs and documents named in this chat;
+ *  5. labels everything as data: the person's words stay theirs, studio's page summary is studio's, and artifact
+ *     content and run outputs are fenced data the seat must never take instructions from.
+ *
+ * The block rides the turn's instructions after the person's words; the binding (what was given, and what was
+ * refused) is recorded as the turn's `context` transcript record, so a later turn can name what this one saw.
+ *
+ * Two phases: {@link buildTurnContext} reads and assembles everything in memory (it awaits), and the result's
+ * `publish()` writes the copies and briefs synchronously. The route calls `publish()` only after its last await and
+ * generation check, so a message whose chat was closed (and its id reopened) meanwhile writes nothing into the new
+ * chat's scratch root.
+ */
+import { z } from 'zod';
+import type { ChatContextBinding, ChatTranscriptRecord, SessionView } from '../core/types.js';
+/** The Unfiled mount in an artifact ref (studio's mount alias `default` is read as it). */
+export declare const UNFILED_MOUNT = "_unfiled";
+/** `<mount>/<doc>`: a project id or `_unfiled`, then interactive's document-name grammar. */
+export declare const ARTIFACT_REF: RegExp;
+/** A `data-wid`: what interactive stamps on each addressable node. */
+export declare const ANCHOR_WID: RegExp;
+/** `context.page`, in characters. */
+export declare const CONTEXT_PAGE_MAX: number;
+export declare const CONTEXT_ANCHORS_MAX = 16;
+/** A version copy past this size is not made: the seat is told to open it in studio. */
+export declare const ARTIFACT_COPY_MAX: number;
+/** Runs briefed in one turn, at most. */
+export declare const RUNS_PER_TURN_MAX = 8;
+/** Run ids looked at in one turn, at most (the rest are named as not looked at). */
+export declare const RUN_TOKENS_MAX = 24;
+/** The strict wire schema of `ChatMessageBody.context` (api-types 0.169.0). */
+export declare const ChatMessageContextSchema: z.ZodObject<{
+    artifact: z.ZodOptional<z.ZodObject<{
+        ref: z.ZodString;
+        version: z.ZodNumber;
+        anchors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strict", z.ZodTypeAny, {
+        version: number;
+        ref: string;
+        anchors?: string[] | undefined;
+    }, {
+        version: number;
+        ref: string;
+        anchors?: string[] | undefined;
+    }>>;
+    appearance: z.ZodOptional<z.ZodObject<{
+        theme: z.ZodOptional<z.ZodString>;
+        accent_h: z.ZodOptional<z.ZodNumber>;
+        accent_s: z.ZodOptional<z.ZodNumber>;
+        accent_l: z.ZodOptional<z.ZodNumber>;
+        ambient: z.ZodOptional<z.ZodBoolean>;
+        ambient_still: z.ZodOptional<z.ZodBoolean>;
+        previewOf: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        theme?: string | undefined;
+        accent_h?: number | undefined;
+        accent_s?: number | undefined;
+        accent_l?: number | undefined;
+        ambient?: boolean | undefined;
+        ambient_still?: boolean | undefined;
+        previewOf?: string | undefined;
+    }, {
+        theme?: string | undefined;
+        accent_h?: number | undefined;
+        accent_s?: number | undefined;
+        accent_l?: number | undefined;
+        ambient?: boolean | undefined;
+        ambient_still?: boolean | undefined;
+        previewOf?: string | undefined;
+    }>>;
+    page: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    artifact?: {
+        version: number;
+        ref: string;
+        anchors?: string[] | undefined;
+    } | undefined;
+    page?: string | undefined;
+    appearance?: {
+        theme?: string | undefined;
+        accent_h?: number | undefined;
+        accent_s?: number | undefined;
+        accent_l?: number | undefined;
+        ambient?: boolean | undefined;
+        ambient_still?: boolean | undefined;
+        previewOf?: string | undefined;
+    } | undefined;
+}, {
+    artifact?: {
+        version: number;
+        ref: string;
+        anchors?: string[] | undefined;
+    } | undefined;
+    page?: string | undefined;
+    appearance?: {
+        theme?: string | undefined;
+        accent_h?: number | undefined;
+        accent_s?: number | undefined;
+        accent_l?: number | undefined;
+        ambient?: boolean | undefined;
+        ambient_still?: boolean | undefined;
+        previewOf?: string | undefined;
+    } | undefined;
+}>;
+/** The parsed body field (the wire's `ChatMessageContext`, as zod reads it). */
+export type ParsedChatMessageContext = z.infer<typeof ChatMessageContextSchema>;
+export interface ParsedRef {
+    /** Canonical: `_unfiled` for an Unfiled document. */
+    mount: string;
+    doc: string;
+    /** The project the mount names (`default` for Unfiled). */
+    projectId: string;
+    ref: string;
+}
+/** Parse and canonicalize an artifact ref; `null` when it is not one. */
+export declare function parseArtifactRef(ref: string): ParsedRef | null;
+/** The mount a chat's project is (`null` = a chat in no project). */
+export declare function chatMount(projectId: string | null | undefined): string | null;
+export interface ChatContextDeps {
+    /** The docs root a project id resolves to (`default` = Unfiled); `null` = no such project. */
+    docsRoot(projectId: string): Promise<string | null>;
+    /** Every run, decorated as `GET /runs` serves it (`project_id`, `document_id`, `chat_id`, `title`, times). */
+    runs(): Promise<SessionView[]>;
+    /** A unit's captured output. */
+    workOutput(unitId: string): Promise<string | null>;
+    /** The run's acceptance line. */
+    acceptanceLine?(view: SessionView): Promise<string | null>;
+    /** The style recorded when the document was created (`ppt`, `web`, …), when there is one. */
+    docStyle?(docsRoot: string, doc: string): string | undefined;
+}
+export interface TurnContextInput {
+    chatId: string;
+    /** The chat's scratch root (`scope.cwd`). */
+    scratchRoot: string;
+    /** The project the chat is filed in; `null` = none. */
+    projectId: string | null;
+    /** The person's typed words. */
+    text: string;
+    context?: ParsedChatMessageContext | undefined;
+    /** The chat's transcript so far. */
+    records: readonly ChatTranscriptRecord[];
+    /** This chat's attachment ids. */
+    attachmentIds: readonly string[];
+}
+export interface TurnContext {
+    /** The section appended to the turn's instructions after the person's words; `''` when there is nothing. */
+    block: string;
+    /** What to record as the turn's `context` transcript record; `null` when nothing was given or refused. */
+    binding: ChatContextBinding | null;
+    /**
+     * Write the copies and briefs the block names into the scratch root. Synchronous, so the route can call it after
+     * its last await. Throws when the scratch root is not what it was (a link, a non-directory, a planted entry).
+     */
+    publish(): void;
+}
+/** Whether this platform can open files beneath a root without following links (`beneath.ts`). */
+export declare function beneathSupported(): boolean;
+/** The directories the seat reads the copies and briefs from: read roots of the chat's run, made at its launch. */
+export declare function contextReadRoots(scratchRoot: string): {
+    open: string;
+    context: string;
+};
+/**
+ * The scratch root as a seat sees it: its real path. A seat in a container sees a read root at its canonical path
+ * only (macOS's `/var/folders/…` is `/private/var/folders/…`; the non-canonical spelling does not exist in a Linux
+ * seat), so every path crew hands the seat, and every read root it launches with, is the real one.
+ */
+export declare function seatPathOf(path: string): string;
+/** Create `dir` (one level below the chat's scratch root, private), proven a real directory beneath it, never a link. */
+export declare function ensureRealDir(dir: string): string;
+interface RunToken {
+    token: string;
+    /** Said as a run (`run 1a2b3c4d`, `runs a, b and c`, `run:<id>`, a run chip): an unresolved one is reported. */
+    explicit: boolean;
+}
+/**
+ * The run ids named in the person's words: every run-shaped hex id (a full uuid or an 8–32 digit prefix), explicit
+ * when said as a run (`run …`, a `runs …, … and …` list, `run:<id>` for any id); and in studio's page summary only
+ * the run of the page they are on (silently, when it is not a run) and the runs they added as chips (explicitly) —
+ * never its recent-runs list.
+ */
+export declare function runTokensOf(text: string, page: string | undefined): RunToken[];
+/** Build the turn's block and binding in memory; `publish()` writes its files. Throws only on a fault of crew itself. */
+export declare function buildTurnContext(input: TurnContextInput, deps: ChatContextDeps): Promise<TurnContext>;
+/**
+ * Whether `<docsRoot>/<doc>` is a real document directory inside the docs root whose latest version (0 included) is
+ * a regular file (`POST /chats {seedFromArtifact}`'s access check): `ok`, `missing`, or `unsupported` (this platform
+ * cannot open files without following links). Everything is opened beneath the docs root: no link is followed in any
+ * component.
+ */
+export declare function artifactStatus(docsRoot: string, doc: string): 'ok' | 'missing' | 'unsupported';
+/** Whether `<docsRoot>/<doc>` is a document crew can read ({@link artifactStatus} `ok`). */
+export declare function artifactExists(docsRoot: string, doc: string): boolean;
+/**
+ * DES-CHAT-ARTIFACTS-001 §4.2-§4.3 (A2): the latest version of `<docsRoot>/<doc>`, read the way {@link artifactStatus}
+ * reads it (beneath the docs root, no link followed in any folder), or `null` when it is not a document. A proposal
+ * records it as a refine's base, and Go checks it has not moved.
+ */
+export declare function artifactHead(docsRoot: string, doc: string): number | null;
+/**
+ * What crew recorded about a document when it was created and drafted (`crew-grounding.json`), read beneath the docs
+ * root like every other A1 read (capped, non-blocking, no link followed): the style, and the repositories it was
+ * grounded on — the draft launch's resolved list when there is one, else the create request's — however many the
+ * writer recorded. `null` when there is no sidecar; `{unreadable}` when there is one crew cannot read or does not
+ * recognise (never read as "no repositories": a seed then refuses rather than skipping its membership check).
+ */
+export declare function readGroundingBeneath(docsRoot: string, doc: string): {
+    style?: string;
+    repoRefs: string[];
+} | {
+    unreadable: true;
+} | null;
+/** sha256 of a string, hex (tests and the route's binding). */
+export declare function sha256Hex(s: string | Buffer): string;
+export {};
+//# sourceMappingURL=chat-context.d.ts.map

package/dist/api/chat-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-context.d.ts","sourceRoot":"","sources":["../../src/api/chat-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAKH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,kBAAkB,EAAE,oBAAoB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAM9F,2FAA2F;AAC3F,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,6FAA6F;AAC7F,eAAO,MAAM,YAAY,QAA6E,CAAC;AACvG,sEAAsE;AACtE,eAAO,MAAM,UAAU,QAAwC,CAAC;AAKhE,qCAAqC;AACrC,eAAO,MAAM,gBAAgB,QAAY,CAAC;AAC1C,eAAO,MAAM,mBAAmB,KAAK,CAAC;AACtC,wFAAwF;AACxF,eAAO,MAAM,iBAAiB,QAAkB,CAAC;AAGjD,yCAAyC;AACzC,eAAO,MAAM,iBAAiB,IAAI,CAAC;AACnC,oFAAoF;AACpF,eAAO,MAAM,cAAc,KAAK,CAAC;AAUjC,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAyB1B,CAAC;AAEZ,gFAAgF;AAChF,MAAM,MAAM,wBAAwB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,wBAAwB,CAAC,CAAC;AAEhF,MAAM,WAAW,SAAS;IACxB,qDAAqD;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,2DAA2D;IAC3D,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAM9D;AAED,qEAAqE;AACrE,wBAAgB,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAG7E;AAQD,MAAM,WAAW,eAAe;IAC9B,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACpD,8GAA8G;IAC9G,IAAI,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC/B,gCAAgC;IAChC,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACnD,iCAAiC;IACjC,cAAc,CAAC,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC3D,6FAA6F;IAC7F,QAAQ,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC9D;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,WAAW,EAAE,MAAM,CAAC;IACpB,uDAAuD;IACvD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,wBAAwB,GAAG,SAAS,CAAC;IAC/C,oCAAoC;IACpC,OAAO,EAAE,SAAS,oBAAoB,EAAE,CAAC;IACzC,kCAAkC;IAClC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,WAAW;IAC1B,4GAA4G;IAC5G,KAAK,EAAE,MAAM,CAAC;IACd,0GAA0G;IAC1G,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACnC;;;OAGG;IACH,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,kGAAkG;AAClG,wBAAgB,gBAAgB,IAAI,OAAO,CAE1C;AAED,mHAAmH;AACnH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAEvF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAM/C;AAUD,yHAAyH;AACzH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOjD;AA+PD,UAAU,QAAQ;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,gHAAgH;IAChH,QAAQ,EAAE,OAAO,CAAC;CACnB;AAWD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,EAAE,CA6C9E;AA2CD,yHAAyH;AACzH,wBAAsB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAgN3G;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,aAAa,CAW9F;AAED,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAErE;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAOzE;AAMD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,UAAU,EAAE,IAAI,CAAA;CAAE,GAAG,IAAI,CAiBxI;AAED,+DAA+D;AAC/D,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,CAEpD"}