@crouter/api 0.3.377

package/dist/shared/generated-context.d.ts

@@ -0,0 +1,79 @@
+/** Custom message carrying the node's session-start bearings. */
+export declare const CONTEXT_INTRO_CUSTOM_TYPE = "crtr-context";
+/** Custom message carrying an ambient situational-context update. */
+export declare const SITUATIONAL_CONTEXT_CUSTOM_TYPE = "crtr-situational-context";
+/** Custom message used when a context-size nudge waits for the next turn. */
+export declare const CONTEXT_NUDGE_CUSTOM_TYPE = "crtr-context-nudge";
+/** Custom message that opens a review companion's visible transcript. */
+export declare const REVIEW_BOUNDARY_CUSTOM_TYPE = "crtr-review-boundary";
+/** Generic completion mandate issued by the terminal-node stop guard. */
+export declare const STALL_REPROMPT: string;
+/** The daemon's parking mandate for an isolated turn. It leaves current truth,
+ * supporting material when needed, lasting lessons, and one deferred update;
+ * the main conversation remains untouched and resumes without a fresh cycle. */
+export declare const PARK_SUMMARY_PROMPT: string;
+/** Static recovery prompts shared by the broker producer and display classifier. */
+export declare const AUTH_FAULT_RECOVERY_BODY = "Provider credentials were just updated (a new login landed). Your previous turn stopped on a provider authentication failure. Continue from where you left off and retry the work that failed.";
+export declare const CONNECTION_FAULT_RECOVERY_BODY = "The network connection is back online. Your previous turn stopped on a connection error (the network was down). Continue from where you left off and retry the work that failed.";
+export declare const PROVIDER_FAULT_RECOVERY_BODY = "Your previous turn stopped on a provider fault. Continue from where you left off and retry the work that failed.";
+export type ModelFallbackRecoveryReason = 'credential' | 'not-found';
+/** Format the stop guard's dynamic structured-output mandate. */
+export declare function formatStructuredOutputReprompt(schema: string): string;
+/** Keep model-fallback guidance editable without making it a reader contract. */
+export declare function formatModelFallbackRecovery(previousModel: string, nextModel: string, reason: ModelFallbackRecoveryReason): string;
+export interface GeneratedContextMessageLike {
+    role?: string;
+    customType?: string;
+    content?: unknown;
+}
+export type CardEntryDisposition = 'report' | 'human-answer' | 'human-canceled';
+export interface CardEntry {
+    disposition: CardEntryDisposition;
+    kind: string;
+    body: string;
+    ref?: string;
+}
+export interface CardSender {
+    id: string;
+    updates: number;
+    finished: boolean;
+    entries: CardEntry[];
+}
+/** An already-resolved inbox entry supplied to the pure digest formatter. */
+export interface InboxCardEntry {
+    kind: string;
+    body: string;
+    ref?: string;
+    disposition?: CardEntryDisposition;
+}
+/** An already-resolved sender section supplied to the pure digest formatter. */
+export interface InboxCardSection {
+    id: string;
+    entries: readonly InboxCardEntry[];
+}
+export interface GeneratedCard {
+    kind: string;
+    facts: Readonly<Record<string, string>>;
+    body: string;
+    senders: CardSender[];
+}
+/** Plain text from a generated message's string or text-block content. */
+export declare function generatedContextText(message: GeneratedContextMessageLike): string;
+/** Wrap a user-role runtime message in its whole-message card envelope. */
+export declare function formatCard(kind: string, facts: Record<string, string | number | boolean | undefined>, body: string): string;
+/** Wrap a card whose body is DATA, not markup — the only escape on the API
+ *  path, so a caller can neither emit a malformed card nor smuggle markup into
+ *  one. `formatCard` keeps its raw body for the trusted crouter producers that
+ *  deliberately nest markup (bearings blocks, the inbox `<from>`/`<entry>`
+ *  grammar `parseInboxBody` depends on). */
+export declare function formatDataCard(kind: string, facts: Record<string, string | number | boolean | undefined>, body: string): string;
+/** Parse a runtime envelope, with pre-envelope customType compatibility. */
+export declare function parseCard(message: GeneratedContextMessageLike): GeneratedCard | null;
+/** Whether an inbox entry is the person's own words. A `human-answer` entry
+ *  whose body is itself a runtime card is a runtime notice — review approvals
+ *  were delivered that way before they became plain prose — never speech. */
+export declare function isHumanWordsEntry(entry: CardEntry): boolean;
+/** Explain how an inbox entry's ref is read without guessing its filesystem location. */
+export declare function formatInboxRefInstruction(ref: string): string;
+/** Format a complete inbox card from report bodies resolved by the caller. */
+export declare function formatInboxCard(sections: readonly InboxCardSection[]): string;

package/dist/shared/generated-context.js

@@ -0,0 +1,232 @@
+// Runtime-card grammar for crouter-authored context messages.
+//
+// Every runtime message carries one whole-message envelope. customType only
+// controls delivery and visibility; parsing stays independent of runtime and clients.
+/** Custom message carrying the node's session-start bearings. */
+export const CONTEXT_INTRO_CUSTOM_TYPE = 'crtr-context';
+/** Custom message carrying an ambient situational-context update. */
+export const SITUATIONAL_CONTEXT_CUSTOM_TYPE = 'crtr-situational-context';
+/** Custom message used when a context-size nudge waits for the next turn. */
+export const CONTEXT_NUDGE_CUSTOM_TYPE = 'crtr-context-nudge';
+/** Custom message that opens a review companion's visible transcript. */
+export const REVIEW_BOUNDARY_CUSTOM_TYPE = 'crtr-review-boundary';
+/** Generic completion mandate issued by the terminal-node stop guard. */
+export const STALL_REPROMPT = "You've stopped but you're not waiting on anyone and haven't finished. " +
+    "Pipe the result to `crtr push final` through a single-quoted heredoc if the work is done, or use `crtr human send` if you are blocked or need the user.";
+/** The daemon's parking mandate for an isolated turn. It leaves current truth,
+ * supporting material when needed, lasting lessons, and one deferred update;
+ * the main conversation remains untouched and resumes without a fresh cycle. */
+export const PARK_SUMMARY_PROMPT = 'This conversation has been idle with nothing left to wake it, so it is being concluded. This is your last turn. Use it to leave a trustworthy inheritance, not to restart or broaden the work. Do these four things now, then stop.\n\n'
+    + '1. Establish current truth. Check only state that may have changed outside the transcript and matters to resuming—such as the working tree, a remote run, or an external decision. Do not start new work; perform only a quick check needed to avoid recording an unverified claim. If no mandate or work ever began, record that plainly in the inheritance and keep every artifact minimal.\n\n'
+    + '2. Put supporting material in documents you own (`crtr doc write`) only when it is needed to keep the inheritance concise. Rewrite existing living documents rather than leave superseded versions. Task state, identifiers, and recovery detail belong here, under this node, not under a longer-lived owner.\n\n'
+    + '3. Give a longer-lived owner (`--owner repo|profile|user`) only to a non-obvious, reusable lesson that should survive this task and is not already recorded. Read `crtr doc write -h`, search before writing (`crtr canvas search`), and choose the narrowest owner that will reach the next agent who needs it. Do not put a conversation recap, task status, recovery handles, or facts already captured in code or docs into such a document.\n\n'
+    + '4. Push exactly one regular update with `crtr push update --tier deferred`, never `crtr push final`. Write for someone who has not seen this conversation: name the work in plain terms, say where it stands, and say what remains or is blocked. Put the current outcome in the first line; include only needed decisions and recovery handles, then stop.';
+/** Static recovery prompts shared by the broker producer and display classifier. */
+export const AUTH_FAULT_RECOVERY_BODY = 'Provider credentials were just updated (a new login landed). Your previous turn stopped on a provider authentication failure. Continue from where you left off and retry the work that failed.';
+export const CONNECTION_FAULT_RECOVERY_BODY = 'The network connection is back online. Your previous turn stopped on a connection error (the network was down). Continue from where you left off and retry the work that failed.';
+export const PROVIDER_FAULT_RECOVERY_BODY = 'Your previous turn stopped on a provider fault. Continue from where you left off and retry the work that failed.';
+const REVIEW_APPROVAL_OPEN = '<crtr-review-approval>';
+const REVIEW_APPROVAL_CLOSE = '</crtr-review-approval>';
+const MODEL_FALLBACK_RECOVERY_OPEN = '<model-fallback-recovery>';
+const MODEL_FALLBACK_RECOVERY_CLOSE = '</model-fallback-recovery>';
+const STRUCTURED_OUTPUT_REPROMPT_PREFIX = 'You must submit a result matching the required schema with `crtr push result` before you can stop, or decline it with `crtr push result --decline "<reason>" --code <token>` when the schema cannot be honestly satisfied. You cannot finish or go dormant any other way while this request is pending.\n\nRequired schema:\n\n```json\n';
+const STRUCTURED_OUTPUT_REPROMPT_SUFFIX = '\n```';
+/** Format the stop guard's dynamic structured-output mandate. */
+export function formatStructuredOutputReprompt(schema) {
+    return `${STRUCTURED_OUTPUT_REPROMPT_PREFIX}${schema}${STRUCTURED_OUTPUT_REPROMPT_SUFFIX}`;
+}
+/** Keep model-fallback guidance editable without making it a reader contract. */
+export function formatModelFallbackRecovery(previousModel, nextModel, reason) {
+    return reason === 'credential'
+        ? `The previous model (${previousModel}) had no usable provider credential, so you were automatically switched to ${nextModel}. Continue the task from where the failed turn left off.`
+        : `The previous model (${previousModel}) was unavailable (provider 404 not_found), so you were automatically switched to ${nextModel}. Continue the task from where the failed turn left off.`;
+}
+function legacyCustomTypeKind(customType) {
+    switch (customType) {
+        case CONTEXT_NUDGE_CUSTOM_TYPE: return 'context-nudge';
+        case CONTEXT_INTRO_CUSTOM_TYPE: return 'bearings';
+        case REVIEW_BOUNDARY_CUSTOM_TYPE: return 'review-boundary';
+        case SITUATIONAL_CONTEXT_CUSTOM_TYPE: return 'situational';
+        default: return undefined;
+    }
+}
+const XML_ATTRIBUTE_NAME = /^[A-Za-z_:][A-Za-z0-9_:.-]*$/;
+const ATTRIBUTE_RE = /\s+([A-Za-z_:][A-Za-z0-9_:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/gy;
+function escapeXmlAttribute(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('>', '&gt;')
+        .replaceAll('"', '&quot;')
+        .replaceAll("'", '&apos;');
+}
+function escapeXmlText(value) {
+    return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;');
+}
+function unescapeXmlAttribute(value) {
+    return value.replace(/&(?:amp|lt|gt|quot|apos);/g, (entity) => ({
+        '&amp;': '&',
+        '&lt;': '<',
+        '&gt;': '>',
+        '&quot;': '"',
+        '&apos;': "'",
+    })[entity]);
+}
+function parseAttributes(source) {
+    const attributes = {};
+    ATTRIBUTE_RE.lastIndex = 0;
+    let index = 0;
+    while (index < source.length) {
+        if (/^\s*$/.test(source.slice(index)))
+            break;
+        ATTRIBUTE_RE.lastIndex = index;
+        const match = ATTRIBUTE_RE.exec(source);
+        if (match === null)
+            return null;
+        const [, key, doubleQuoted, singleQuoted] = match;
+        if (key === undefined || Object.hasOwn(attributes, key))
+            return null;
+        attributes[key] = unescapeXmlAttribute(doubleQuoted ?? singleQuoted ?? '');
+        index = ATTRIBUTE_RE.lastIndex;
+    }
+    return attributes;
+}
+function formatAttributes(attributes) {
+    return Object.entries(attributes)
+        .filter(([, value]) => value !== undefined)
+        .map(([key, value]) => {
+        if (!XML_ATTRIBUTE_NAME.test(key))
+            throw new Error(`Invalid XML attribute name: ${key}`);
+        return ` ${key}="${escapeXmlAttribute(String(value))}"`;
+    })
+        .join('');
+}
+/** Plain text from a generated message's string or text-block content. */
+export function generatedContextText(message) {
+    if (typeof message.content === 'string')
+        return message.content;
+    if (!Array.isArray(message.content))
+        return '';
+    return message.content
+        .filter((block) => typeof block === 'object'
+        && block !== null
+        && block.type === 'text'
+        && typeof block.text === 'string')
+        .map((block) => block.text)
+        .join('');
+}
+/** Wrap a user-role runtime message in its whole-message card envelope. */
+export function formatCard(kind, facts, body) {
+    if (kind === '')
+        throw new Error('Runtime card kind is required');
+    if (Object.hasOwn(facts, 'kind'))
+        throw new Error('Runtime card facts cannot replace kind');
+    return `<runtime${formatAttributes({ kind, ...facts })}>${body}</runtime>`;
+}
+/** Wrap a card whose body is DATA, not markup — the only escape on the API
+ *  path, so a caller can neither emit a malformed card nor smuggle markup into
+ *  one. `formatCard` keeps its raw body for the trusted crouter producers that
+ *  deliberately nest markup (bearings blocks, the inbox `<from>`/`<entry>`
+ *  grammar `parseInboxBody` depends on). */
+export function formatDataCard(kind, facts, body) {
+    return formatCard(kind, facts, escapeXmlText(body));
+}
+function parseInboxBody(body) {
+    const senders = [];
+    const fromRe = /<from\b([^>]*)>([\s\S]*?)<\/from>/g;
+    for (const fromMatch of body.matchAll(fromRe)) {
+        const attributes = parseAttributes(fromMatch[1] ?? '');
+        if (attributes?.id === undefined)
+            continue;
+        const entries = [];
+        const entryBody = fromMatch[2] ?? '';
+        const entryRe = /<entry\b([^>]*)>([\s\S]*?)<\/entry>/g;
+        for (const entryMatch of entryBody.matchAll(entryRe)) {
+            const entryAttributes = parseAttributes(entryMatch[1] ?? '');
+            if (entryAttributes?.kind === undefined)
+                continue;
+            const disposition = entryAttributes.disposition === 'human-answer' || entryAttributes.disposition === 'human-canceled'
+                ? entryAttributes.disposition
+                : 'report';
+            entries.push({
+                kind: entryAttributes.kind,
+                disposition,
+                body: unescapeXmlAttribute(entryMatch[2] ?? ''),
+                ...(entryAttributes.ref === undefined ? {} : { ref: entryAttributes.ref }),
+            });
+        }
+        // `updates` and `finished` are derived from the entry list; pre-cut
+        // scrollback still carries them as attributes, honored when present.
+        const legacyUpdates = attributes.updates === undefined ? Number.NaN : Number(attributes.updates);
+        senders.push({
+            id: attributes.id,
+            updates: Number.isFinite(legacyUpdates) ? legacyUpdates : entries.length,
+            finished: attributes.finished === 'true' || entries.some((entry) => entry.kind === 'final'),
+            entries,
+        });
+    }
+    return senders;
+}
+function cardFor(kind, facts, body, senders) {
+    return { kind, facts, body, senders };
+}
+/** Parse a whole-message runtime envelope, regardless of delivery role. */
+function parseEnvelope(text) {
+    const opening = /^<runtime\b([^>]*)>/.exec(text);
+    if (opening === null || !text.endsWith('</runtime>'))
+        return null;
+    const attributes = parseAttributes(opening[1] ?? '');
+    if (attributes?.kind === undefined)
+        return null;
+    const raw = text.slice(opening[0].length, -'</runtime>'.length);
+    const { kind, ...factValues } = attributes;
+    const facts = Object.freeze(factValues);
+    // A namespaced kind can only have been produced through the API path, whose
+    // renderer is `formatDataCard`, so its body is escaped by construction and
+    // decodes here. A bare kind's body is raw markup written by a core producer.
+    const body = kind.includes(':') ? unescapeXmlAttribute(raw) : raw;
+    return cardFor(kind, facts, body, kind === 'inbox' ? parseInboxBody(body) : []);
+}
+/** Parse a runtime envelope, with pre-envelope customType compatibility. */
+export function parseCard(message) {
+    const text = generatedContextText(message);
+    const envelope = parseEnvelope(text);
+    if (envelope !== null)
+        return envelope;
+    if (message.role !== 'custom')
+        return null;
+    // Pre-envelope custom-message fallback for old sessions. New custom messages
+    // classify through their envelope; customType is delivery metadata only.
+    const kind = legacyCustomTypeKind(message.customType);
+    return kind === undefined ? null : {
+        kind,
+        facts: Object.freeze({}),
+        body: text,
+        senders: [],
+    };
+}
+/** Whether an inbox entry is the person's own words. A `human-answer` entry
+ *  whose body is itself a runtime card is a runtime notice — review approvals
+ *  were delivered that way before they became plain prose — never speech. */
+export function isHumanWordsEntry(entry) {
+    return entry.disposition === 'human-answer' && parseEnvelope(entry.body.trim()) === null;
+}
+/** Explain how an inbox entry's ref is read without guessing its filesystem location. */
+export function formatInboxRefInstruction(ref) {
+    return ref.startsWith('/')
+        ? `Preview only. Read the full body from file \`${ref}\`.`
+        : `Read this report with \`crtr canvas read ${ref}\`.`;
+}
+/** Format a complete inbox card from report bodies resolved by the caller. */
+export function formatInboxCard(sections) {
+    const body = sections.map((section) => {
+        const entries = section.entries.map((entry) => {
+            const disposition = entry.disposition === 'human-answer' || entry.disposition === 'human-canceled'
+                ? entry.disposition
+                : undefined;
+            return `<entry${formatAttributes({ kind: entry.kind, ref: entry.ref, disposition })}>${escapeXmlText(entry.body)}</entry>`;
+        }).join('\n');
+        return `<from${formatAttributes({ id: section.id })}>${entries}</from>`;
+    }).join('\n');
+    return formatCard('inbox', {}, body);
+}

package/dist/shared/predicates.d.ts

@@ -0,0 +1,2 @@
+/** A plain object with named properties: null and arrays are not records. */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/shared/predicates.js

@@ -0,0 +1,4 @@
+/** A plain object with named properties: null and arrays are not records. */
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@crouter/api",
+  "version": "0.3.377",
+  "description": "Typed crtrd /v1 API contract — DTOs, route builders, the error contract, the CrtrClient, and the command-plugin manifest format. Zero runtime dependencies.",
+  "type": "module",
+  "main": "./dist/api/index.js",
+  "types": "./dist/api/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/api/index.d.ts",
+      "import": "./dist/api/index.js"
+    },
+    "./node": {
+      "types": "./dist/api/node-transport.d.ts",
+      "import": "./dist/api/node-transport.js",
+      "require": "./dist/api/node-transport.js",
+      "default": "./dist/api/node-transport.js"
+    },
+    "./plugin-manifest": {
+      "types": "./dist/api/plugin-manifest-schema.d.ts",
+      "import": "./dist/api/plugin-manifest-schema.js"
+    },
+    "./cards": {
+      "types": "./dist/shared/generated-context.d.ts",
+      "import": "./dist/shared/generated-context.js"
+    },
+    "./command-manifest": {
+      "types": "./dist/api/command-manifest/index.d.ts",
+      "import": "./dist/api/command-manifest/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crouton-labs/crouter.git",
+    "directory": "packages/crouter-api"
+  },
+  "license": "GPL-3.0-only"
+}