@north-light/api 0.0.0 → 0.3.414

package/dist/shared/generated-context.js

@@ -0,0 +1,235 @@
+// 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.';
+/** A run node's connection retry. Its broker never probes the network (its
+ *  model calls go through the daemon), so it cannot claim the network is back;
+ *  the attempt itself is the probe. */
+export const RUN_CONNECTION_FAULT_RETRY_BODY = 'Your previous turn stopped on a connection error reaching the model provider. Retrying now: 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_SUFFIX = '\n```';
+/** Format the stop guard's dynamic structured-output mandate. */
+export function formatStructuredOutputReprompt(schema, requestId) {
+    return `You must submit a result matching the required schema before you can stop: call the \`submit_result\` tool with \`request_id: "${requestId}"\` and the JSON in \`result\`, or with \`decline: { reason, code }\` 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${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/inbox-entry-body.d.ts

@@ -0,0 +1,22 @@
+export declare const INLINE_REPORT_MAX_CHARS = 1000;
+/** The rendering fields both inbox projections share. */
+export interface InboxEntryFields {
+    ts: string;
+    from: string | null;
+    from_name?: string;
+    label: string;
+    ref?: string;
+    data?: Record<string, unknown>;
+}
+/** A report document's ref (`<node>/reports/<name>`), else undefined. */
+export declare function reportRefNodeId(ref: string | undefined): string | undefined;
+/** Clip a body to the bounded preview stored beside a spilled message body. */
+export declare function clipBody(body: string): {
+    text: string;
+    clipped: boolean;
+};
+export declare function inlineBody(entry: Pick<InboxEntryFields, 'data' | 'label'>): string;
+/** One entry's card body: an inlined short report, a bounded inline message body, an event
+ *  push rendered from its metadata, or the label. `report` is the report document's body when
+ *  the caller could read it. */
+export declare function renderEntryBody(entry: InboxEntryFields, report: string | null): string;

package/dist/shared/inbox-entry-body.js

@@ -0,0 +1,116 @@
+// One inbox entry's card body, shared by the daemon (kickoff digest) and broker (live inbox) renderers.
+import { formatInboxRefInstruction } from './generated-context.js';
+const BODY_MAX_LINES = 12;
+const BODY_MAX_CHARS = 1000;
+export const INLINE_REPORT_MAX_CHARS = 1000;
+/** A report document's ref (`<node>/reports/<name>`), else undefined. */
+export function reportRefNodeId(ref) {
+    const match = ref === undefined ? null : /^([a-z0-9-]+)\/reports\/[^/]+$/.exec(ref);
+    return match?.[1];
+}
+/** Clip a body to the bounded preview stored beside a spilled message body. */
+export function clipBody(body) {
+    let text = body;
+    let clipped = false;
+    const lines = text.split('\n');
+    if (lines.length > BODY_MAX_LINES) {
+        text = lines.slice(0, BODY_MAX_LINES).join('\n');
+        clipped = true;
+    }
+    if (text.length > BODY_MAX_CHARS) {
+        text = text.slice(0, BODY_MAX_CHARS);
+        clipped = true;
+    }
+    return { text: text.trimEnd(), clipped };
+}
+export function inlineBody(entry) {
+    const body = typeof entry.data?.['body'] === 'string' ? String(entry.data['body']).trim() : '';
+    return body === '' || body === entry.label ? '' : body;
+}
+function pushOf(entry) {
+    const push = entry.data?.['push'];
+    return typeof push === 'object' && push !== null && typeof push.event === 'string' ? push : null;
+}
+/** The name a reader resolves the object by: `<owner handle>/<name>`, or the owner's id on an older push. */
+function objectRef(o) {
+    const owner = o.owner_handle ?? o.owner;
+    return owner === null || owner === undefined ? o.name : `${owner}/${o.name}`;
+}
+function objectText(o) {
+    if (o.type === 'document')
+        return `[[${objectRef(o)}]]`;
+    if (o.type === 'job')
+        return `job ${o.id} (\`${o.name}\`)`;
+    if (o.type === 'node')
+        return `node ${o.name} (${o.id})`;
+    return `${o.type} ${o.name}`;
+}
+function actorText(entry, push) {
+    if (push.actor === null)
+        return 'the runtime';
+    return entry.from_name === undefined || entry.from_name === push.actor ? push.actor : `${entry.from_name} (${push.actor})`;
+}
+function list(value) {
+    return Array.isArray(value) ? value.filter((v) => typeof v === 'string') : [];
+}
+/** One sentence per event: the object, the actor and the pointer — never the act's content. */
+function renderPush(entry, push) {
+    const obj = objectText(push.object);
+    const actor = actorText(entry, push);
+    const a = push.attrs;
+    const readHint = push.object.type === 'document'
+        ? ` Read it with \`crtr canvas read ${objectRef(push.object)}\`.`
+        : '';
+    switch (push.event) {
+        case 'created':
+            return push.object.type === 'node'
+                ? `${actor} created ${obj}${typeof a['kind'] === 'string' ? `, kind ${a['kind']}` : ''}.`
+                : `${actor} created ${obj}.${readHint}`;
+        case 'read': return `${actor} read ${obj}.`;
+        case 'watched': return `${actor} started watching ${obj}.`;
+        case 'deleted': return `${actor} deleted ${obj}.`;
+        case 'edited': {
+            const authors = list(a['authors']);
+            const rationales = list(a['rationales']);
+            const range = typeof a['from_revision'] === 'number' && typeof a['revision'] === 'number' && a['revision'] - a['from_revision'] > 1
+                ? `revisions ${a['from_revision'] + 1}–${a['revision']}` : typeof a['revision'] === 'number' ? `revision ${a['revision']}` : 'a new revision';
+            const by = authors.length === 0 ? actor : authors.join(', ');
+            const why = rationales.length === 0 ? '' : ` Rationale: ${rationales.join('; ')}.`;
+            const merge = a['needs_merge'] === true ? ' Two edits were made from the same revision; read it and edit it to merge them.' : '';
+            const unwatchHint = ` You get this because you read or wrote it; if it no longer concerns your work, stop with \`crtr canvas unwatch ${objectRef(push.object)}\`.`;
+            return `${by} edited ${obj} (${range}).${why}${merge}${readHint}${unwatchHint}`;
+        }
+        case 'messaged': return `${actor} messaged ${obj}.`;
+        case 'sent': return `${actor} sent a message as ${obj}.`;
+        case 'configured': return `${actor} changed the settings of ${obj}${typeof a['changed'] === 'string' ? `: ${a['changed']}` : ''}.`;
+        case 'exited': return `${obj[0].toUpperCase()}${obj.slice(1)} exited with code ${String(a['exit-code'])}. Log: ${String(a['log-path'])}`;
+        case 'killed': {
+            const by = push.actor === null ? '' : ` by ${actor}`;
+            const why = typeof a['reason'] === 'string' ? ` (${a['reason']})` : '';
+            const claim = a['reason'] === 'deadline'
+                ? ` It was canceled at its deadline; claim it with \`crtr node bash extend ${push.object.id} --for <duration>\` next time.`
+                : '';
+            return `${obj[0].toUpperCase()}${obj.slice(1)} was killed${by}${why}.${claim} Log: ${String(a['log-path'])}`;
+        }
+        default: return entry.label;
+    }
+}
+/** One entry's card body: an inlined short report, a bounded inline message body, an event
+ *  push rendered from its metadata, or the label. `report` is the report document's body when
+ *  the caller could read it. */
+export function renderEntryBody(entry, report) {
+    if (report !== null && report.length < INLINE_REPORT_MAX_CHARS && entry.ref !== undefined) {
+        return `${report.trimEnd()}\n\n${formatInboxRefInstruction(entry.ref)}`;
+    }
+    const body = inlineBody(entry);
+    if (body === '') {
+        const push = pushOf(entry);
+        if (push !== null && entry.ref === undefined)
+            return renderPush(entry, push);
+        return entry.ref === undefined ? entry.label : `${entry.label}\n\n${formatInboxRefInstruction(entry.ref)}`;
+    }
+    const { text, clipped } = clipBody(body);
+    if (entry.ref !== undefined)
+        return `${text}\n\n${formatInboxRefInstruction(entry.ref)}`;
+    return clipped ? `${text}\n… (body clipped)` : text;
+}

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/dist/shared/working-activity.d.ts

@@ -0,0 +1,9 @@
+export declare const DEFAULT_WORKING_GERUND = "working";
+export declare const DEFAULT_WORKING_GERUNDS: readonly ["thinking", "planning", "checking", "working"];
+export declare const DEFAULT_WORKING_ACTIVITY = "Working...";
+/** Keep only usable configured labels; malformed or empty lists fall back to working. */
+export declare function normalizeWorkingGerunds(value: unknown): string[];
+/** Format one configured gerund as the activity label shown by every viewer. */
+export declare function formatWorkingActivity(gerund: unknown): string;
+/** Pick one configured gerund when the broker receives a user message. */
+export declare function randomWorkingActivity(value: unknown, random?: () => number): string;

package/dist/shared/working-activity.js

@@ -0,0 +1,27 @@
+export const DEFAULT_WORKING_GERUND = 'working';
+export const DEFAULT_WORKING_GERUNDS = ['thinking', 'planning', 'checking', DEFAULT_WORKING_GERUND];
+export const DEFAULT_WORKING_ACTIVITY = 'Working...';
+/** Keep only usable configured labels; malformed or empty lists fall back to working. */
+export function normalizeWorkingGerunds(value) {
+    if (!Array.isArray(value))
+        return [DEFAULT_WORKING_GERUND];
+    const gerunds = value
+        .filter((entry) => typeof entry === 'string')
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    return gerunds.length > 0 ? gerunds : [DEFAULT_WORKING_GERUND];
+}
+/** Format one configured gerund as the activity label shown by every viewer. */
+export function formatWorkingActivity(gerund) {
+    const normalized = normalizeWorkingGerunds([gerund])[0] ?? DEFAULT_WORKING_GERUND;
+    return `${normalized[0].toUpperCase()}${normalized.slice(1)}...`;
+}
+/** Pick one configured gerund when the broker receives a user message. */
+export function randomWorkingActivity(value, random = Math.random) {
+    const gerunds = normalizeWorkingGerunds(value);
+    const draw = random();
+    const index = Number.isFinite(draw)
+        ? Math.min(gerunds.length - 1, Math.max(0, Math.floor(draw * gerunds.length)))
+        : 0;
+    return formatWorkingActivity(gerunds[index]);
+}