@andorra-labs/code 0.0.0-stage → 0.1.4

package/dist/src/completion.js

@@ -0,0 +1,195 @@
+import { validateJsonSchemaValue } from '../vendor/zcode/source/tool/json-schema.js';
+export const COMPLETION_TOOL = 'complete_agent';
+export const FINAL_RESPONSE_GUIDANCE = "Only when this node is responsible for producing the final user answer, its summary must satisfy the user's response requirements: include complete requested files and exact formatting, including requested code fences, without abbreviation, path substitution, or offers to provide content later. Each fence opens and closes on its own line; a file written to the workspace that the user did not ask to see in the answer is named by path, not reproduced. Intermediate intake, research, and delegation nodes must instead keep a concise handoff and preserve these final-answer acceptance requirements in the downstream task instruction or output; do not implement or reproduce the final deliverable before handing off.";
+/**
+ * How the model lays out text a person reads: the handoff summary and any prose answer. The
+ * transcript renders markdown (headings, lists, fenced code), so the structure it asks for is
+ * what the user actually sees; a single unbroken paragraph is what this guidance exists to prevent.
+ */
+export const RESPONSE_STRUCTURE_GUIDANCE = `Write user-facing text, including the final summary, as structured markdown rather than one unbroken paragraph. Lead with the outcome in one or two sentences, then use short headings (## What changed, ## Verified, ## Not done) and bullet lists for parallel items; put every command, file content, and code sample in a fenced code block whose fences sit on their own lines; keep sentences short and omit filler. Inside a JSON string the line breaks are written as \\n escapes, and they are expected: never flatten the summary into one line to keep the JSON valid. In the tests array, write one short line per check: the check that ran, then its outcome.`;
+/**
+ * The summary is the user's final answer and the transcript renders it as markdown. Weak models
+ * read "valid JSON" as "no newlines" and return one unbroken line, so the field itself says the
+ * breaks are wanted, next to the value they shape.
+ */
+export const SUMMARY_DESCRIPTION = 'Markdown shown to the user as the final answer. Write line breaks as \\n escapes: lead with the outcome, then short headings and bullet lists, and open and close each fenced code block on its own line. Never one unbroken paragraph.';
+export const COMPLETION_GUIDANCE = `Finish with complete_agent alone or final JSON. Todos/artifacts do not finish a node. Compare deliverables and verification evidence with acceptance criteria. Fulfill assigned requirements: intake/research nodes hand off downstream work; implementation nodes finish implementation and verification, not a progress checkpoint. Continue available work. For a concrete external blocker, report the blocker and unfinished work honestly. Use a blocked outcome if available; otherwise the sole outcome permits a terminal report, not a claim that the task is done. ${FINAL_RESPONSE_GUIDANCE} Preserve required fields and valid JSON; escape quotes and Windows backslashes or use C:/repo/file.ts, and write each summary line break as \\n rather than dropping it. Never claim unperformed work.`;
+/** Expand Andorra's artifact shorthand into provider-visible JSON Schema at every depth. */
+function providerOutputSchema(schema) {
+    const { format, properties, items, ...rest } = schema;
+    const expanded = properties || format === 'artifact' ? {
+        ...(format === 'artifact' ? { type: { type: 'string' }, ref: { type: 'string' } } : {}),
+        ...Object.fromEntries(Object.entries(properties ?? {}).map(([key, value]) => [key, providerOutputSchema(value)])),
+    } : undefined;
+    return { ...rest,
+        ...(expanded ? { properties: expanded } : {}),
+        ...(items ? { items: providerOutputSchema(items) } : {}),
+        ...(format === 'artifact' ? { required: [...new Set(['type', 'ref', ...(schema.required ?? [])])] } : {}),
+    };
+}
+/** Native JSON Schema checks plus Andorra's graph-specific artifact/integer contracts. */
+function validateCompletionOutput(schema, value) {
+    const validation = validateJsonSchemaValue(value, providerOutputSchema(schema));
+    if (!validation.valid)
+        throw new Error(validation.errors.map(error => error.replace(/^\$/, 'Agent output')).join('; '));
+    const checkHostContracts = (node, item, path) => {
+        if (node.type === 'integer' && !Number.isSafeInteger(item))
+            throw new Error(`${path}: expected integer`);
+        if (node.format === 'artifact') {
+            const ref = item;
+            if (typeof ref.ref !== 'string' || !/^artifact:\/\/[^/]+\/[^/]+$/.test(ref.ref)) {
+                throw new Error(`${path}: expected an artifact reference object with type and artifact:// ref`);
+            }
+        }
+        if (node.type === 'object') {
+            for (const [key, child] of Object.entries(node.properties ?? {})) {
+                if (Object.hasOwn(item, key))
+                    checkHostContracts(child, item[key], `${path}.${key}`);
+            }
+        }
+        if (node.type === 'array' && node.items) {
+            for (const [index, child] of item.entries())
+                checkHostContracts(node.items, child, `${path}[${index}]`);
+        }
+    };
+    checkHostContracts(schema, value, 'Agent output');
+}
+/** Control-plane completion remains available when the execution-tool budget is exhausted. */
+export function completionTool(options) {
+    const outcomes = options.completionPolicy
+        ? options.completionPolicy.mode === 'single' ? [options.completionPolicy.outcome] : options.completionPolicy.outcomes
+        : undefined;
+    return {
+        name: COMPLETION_TOOL,
+        description: 'Finish this Agent and return its validated result to the graph. Call alone after fulfilling the node requirements. Saving todos or artifacts does not complete the node.',
+        parameters: {
+            type: 'object',
+            properties: {
+                summary: { type: 'string', description: SUMMARY_DESCRIPTION }, tests: { type: 'array', items: { type: 'string', description: 'One short line: the check that ran, then its outcome.' } },
+                ...(outcomes ? { artifacts: { type: 'array', maxItems: 50, items: { type: 'object', properties: { type: { type: 'string' }, ref: { type: 'string' } }, required: ['type', 'ref'], additionalProperties: false } } } : {}),
+                ...(outcomes ? { outcome: { type: 'string', enum: outcomes }, output: providerOutputSchema(options.outputSchema ?? { type: 'object' }) } : {}),
+            },
+            required: ['summary', 'tests', ...(outcomes ? ['outcome', 'output'] : [])],
+            additionalProperties: false,
+        },
+    };
+}
+/** Only a direct, sole model control call can request completion, never a tool observation. */
+export function completionResponse(response) {
+    const call = response.toolCalls.find(call => call.name === COMPLETION_TOOL);
+    if (!call)
+        return { ...response, completionSource: 'final_text' };
+    return { ...response, completionSource: 'complete_agent', toolCalls: [], text: call.arguments, ...(response.toolCalls.length === 1 ? {} : { completionError: 'complete_agent must be called alone; no tools in this batch were executed.' }) };
+}
+/** Classify parser failures without echoing model text, paths, or private analysis. */
+function syntaxFailure(error) {
+    const message = error.message;
+    const position = message.match(/at position (\d+)(?: \(line (\d+) column (\d+)\))?/);
+    const location = position ? ` at position ${position[1]}${position[2] ? ` (line ${position[2]}, column ${position[3]})` : ''}` : '';
+    const category = /bad (?:escaped character|unicode escape)/i.test(message) ? 'invalidEscape'
+        : /bad control character/i.test(message) ? 'unescapedControlCharacter'
+            : /unterminated string/i.test(message) ? 'unterminatedString'
+                : /unexpected end/i.test(message) ? 'unexpectedEnd'
+                    : /unexpected token/i.test(message) ? 'unexpectedToken' : 'syntax';
+    return `Invalid completion JSON [${category}]${location}. Both final text and complete_agent arguments must contain one complete JSON object, without analysis tags or surrounding prose. Use forward slashes for Windows paths (C:/repo/src/file.ts), or escape each backslash; escape quotes inside strings and write line breaks as \\n escapes, keeping the summary's markdown structure. Preserve the completion envelope and required fields. Keep the handoff concise by default, without repeating file contents or the intake transcript. ${FINAL_RESPONSE_GUIDANCE} Keep the enclosing completion valid JSON.`;
+}
+/**
+ * Undo one extra layer of string escaping in a summary. Some models JSON-escape the summary again
+ * inside already-JSON tool arguments, so the parsed text holds a backslash and an "n" where its
+ * line breaks belong, and the transcript draws its markdown as one literal paragraph. The decode
+ * runs only when the text has no real line break and at least two escaped paragraph breaks, so a
+ * summary that merely mentions an escape sequence, or a Windows path, is left as written.
+ * Sessions saved before this decode ran still hold the escaped text, so their readers apply it too
+ * (`displayHistory` in sessions.ts).
+ */
+export function decodeDoubleEscapedSummary(summary, notes) {
+    if (summary.includes('\n') || (summary.match(/\\n\\n/g)?.length ?? 0) < 2)
+        return summary;
+    notes?.push('completion summary arrived with its newlines escaped twice and was decoded');
+    const decoded = { n: '\n', r: '\r', t: '\t', '"': '"', '\\': '\\' };
+    return summary.replace(/\\(["\\nrt])/g, (_, char) => decoded[char]);
+}
+/**
+ * Parse one completion, accepting mechanically imperfect envelopes that are semantically correct.
+ *
+ * `notes`, when provided, collects each host-side coercion ("output arrived as a JSON-encoded
+ * string", "dropped artifacts entries the runtime did not issue"). Those repairs are
+ * deterministic transforms the model cannot achieve by retrying: the artifacts channel can never
+ * hold a pull-request URL, and a model that double-encodes `output` once will do it again. A
+ * rejection for either burns a repair on a coin flip and can end a node whose work is already
+ * done, so they are coerced and recorded instead.
+ */
+export function parseCompletion(text, options, reject, notes) {
+    try {
+        const value = JSON.parse(text.replace(/^```(?:json)?\s*\n?/, '').replace(/\n?```\s*$/, ''));
+        if (options.completionPolicy && value && typeof value === 'object' && !Array.isArray(value)) {
+            const policy = options.completionPolicy;
+            const outcome = value.outcome ?? (policy.mode === 'single' ? policy.outcome : undefined);
+            if (typeof outcome !== 'string' || !(policy.mode === 'single' ? [policy.outcome] : policy.outcomes).includes(outcome))
+                throw new Error("Completion outcome or output does not match the declared contract");
+            let output = value.output ?? (typeof value.summary === 'string' ? { summary: value.summary, tests: value.tests ?? [] } : undefined);
+            if (typeof output === 'string') {
+                // A long context makes models JSON-encode `output` a second time. The decoded value faces
+                // every check below unchanged, so the coercion cannot smuggle a contract violation through.
+                try {
+                    const decoded = JSON.parse(output);
+                    if (decoded && typeof decoded === 'object' && !Array.isArray(decoded)) {
+                        output = decoded;
+                        notes?.push('completion output arrived as a JSON-encoded string and was decoded to an object');
+                    }
+                }
+                catch { /* not JSON: the object check below rejects it with the contract wording */ }
+            }
+            if (!output || typeof output !== 'object' || Array.isArray(output))
+                throw new Error("Completion outcome or output does not match the declared contract");
+            if (options.canonicalTask !== undefined)
+                output.originalTask = options.canonicalTask;
+            if (options.outputSchema)
+                validateCompletionOutput(options.outputSchema, output);
+            const unknownArtifactRefs = [];
+            const validArtifactRefs = (item, path) => {
+                if (!item || typeof item !== 'object')
+                    return true;
+                const ref = item.ref;
+                if ('ref' in item && typeof ref === 'string' && ref.startsWith('artifact://') && !options.artifactStore?.has(item)) {
+                    unknownArtifactRefs.push(`${path} ${ref}`);
+                    return false;
+                }
+                return Object.entries(item).every(([key, child]) => validArtifactRefs(child, `${path}.${key}`));
+            };
+            if (!validArtifactRefs(output, 'Agent output'))
+                throw new Error(`Output contains an unknown artifact reference (${unknownArtifactRefs.join('; ')}); re-create it with write_artifact and use the reference it returns, or remove the field`);
+            if (value.artifacts !== undefined) {
+                if (!Array.isArray(value.artifacts) || value.artifacts.length > 50)
+                    throw new Error("Artifacts must be an array of at most 50 runtime references");
+                // The artifacts channel holds only references the runtime issued (artifacts.ts). A
+                // pull-request URL or a workspace path is an external reference the store can never
+                // contain, so rejecting it asked for a repair no retry could produce; external
+                // references belong in output, and the drop is recorded.
+                const registered = [];
+                const dropped = [];
+                for (const artifact of value.artifacts) {
+                    if (options.artifactStore?.has(artifact))
+                        registered.push(artifact);
+                    else
+                        dropped.push(typeof artifact?.type === 'string' ? artifact.type : 'untyped');
+                }
+                if (dropped.length)
+                    notes?.push(`artifacts[] carried ${dropped.length} ${dropped.length === 1 ? 'entry' : 'entries'} the runtime did not issue (${dropped.join(', ')}); only artifact:// references from write_artifact ride the artifacts channel — carry external references in output`);
+                value.artifacts = registered;
+            }
+            const summary = typeof value.summary === 'string' && value.summary.trim() ? value.summary : typeof output.summary === 'string' && output.summary.trim() ? output.summary : typeof output.implementationSummary === 'string' ? output.implementationSummary : JSON.stringify(output).slice(0, 2000);
+            return { summary: decodeDoubleEscapedSummary(summary, notes),
+                tests: Array.isArray(value.tests) && value.tests.every((item) => typeof item === 'string') ? value.tests : [], outcome, output,
+                artifacts: value.artifacts ?? [] };
+        }
+        if (value && typeof value.summary === 'string' && value.summary.trim()
+            && Array.isArray(value.tests) && value.tests.every((x) => typeof x === 'string')) {
+            return { summary: decodeDoubleEscapedSummary(value.summary, notes), tests: value.tests };
+        }
+        throw new Error("Completion needs a nonempty summary and a tests array of strings");
+    }
+    catch (error) {
+        reject(error instanceof SyntaxError ? syntaxFailure(error) : error instanceof Error ? error.message : "Invalid completion JSON");
+    }
+}

package/dist/src/config.d.ts

@@ -0,0 +1,163 @@
+import type { DecisionConfig } from './decision/types.js';
+import { type EfficiencyConfig } from './efficiency.js';
+import { type ProviderConfig } from './providers.js';
+import type { CodeIntelConfig } from './code-intelligence/types.js';
+import type { MemoryConfig } from './memory/types.js';
+import { type AnalyticsConfig } from './analytics.js';
+import { type PermissionMode } from './permissions.js';
+import { type Limits } from './limits.js';
+import type { ProjectEntry, RemoteConfig } from './remote/types.js';
+/**
+ * Run bounds an installation may set for itself.
+ *
+ * Every key is optional and every unset key means unlimited, so an install that configures
+ * nothing runs without a wall clock or an iteration ceiling. `wallTimeMs` and `maxIterations`
+ * also accept `0` as an explicit spelling of unlimited. `maxToolCalls` does not: there a
+ * literal `0` is a real ceiling that allows completion without tools.
+ */
+export interface LimitsConfig {
+    maxIterations?: number;
+    wallTimeMs?: number;
+    maxToolCalls?: number;
+    maxContextChars?: number;
+    maxCompletionRepairs?: number;
+}
+export type McpServerConfig = {
+    transport: 'stdio';
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+    enabled?: boolean;
+} | {
+    transport: 'http';
+    url: string;
+    headers?: Record<string, string>;
+    enabled?: boolean;
+};
+export interface Config {
+    version: 1;
+    provider: string;
+    providers: ProviderConfig[];
+    graph?: string;
+    graphSelections?: Record<string, string>;
+    codeIntel?: CodeIntelConfig;
+    memory?: MemoryConfig;
+    analytics?: AnalyticsConfig;
+    commandMemory?: boolean;
+    jevEnabled?: boolean;
+    decisions?: DecisionConfig;
+    efficiency?: EfficiencyConfig;
+    limits?: LimitsConfig;
+    extensions?: {
+        disabledSkills?: string[];
+        disabledPlugins?: string[];
+    };
+    mcpServers?: Record<string, McpServerConfig>;
+    workspacePermissions?: Record<string, PermissionMode>;
+    remote?: RemoteConfig;
+    projects?: ProjectEntry[];
+    /**
+     * The provider/model external hosts (Claude CLI, Codex CLI) must name for subagent runs.
+     * Mandatory at run time rather than load time: an unset pair is answered with the available
+     * providers/models so the calling agent can ask its user and retry with the pick.
+     */
+    externalSubagent?: {
+        provider: string;
+        model: string;
+    };
+    /**
+     * Instructions that take the workspace guide's place at the top of its hierarchy: when set, they
+     * are used instead of ANDORRA.md, AGENTS.md or agents.md for every run of this installation.
+     */
+    systemPromptOverride?: string;
+    /** Days without activity after which a session is archived automatically; unset means never. */
+    autoArchiveDays?: number;
+}
+/** The longest override the setting accepts: the same bound the workspace guide is clipped to. */
+export declare const MAX_SYSTEM_PROMPT_OVERRIDE = 16000;
+export declare const AUTO_ARCHIVE_MIN_DAYS = 1;
+export declare const AUTO_ARCHIVE_MAX_DAYS = 30;
+export declare function configDirectory(): string;
+export declare function validateConfig(value: unknown): Config;
+/**
+ * The saved external-subagent pair follows the providers it names.
+ *
+ * A provider that is removed, or a model that is no longer on its list, leaves the pair naming a
+ * model that does not exist, and the configuration would be refused for a setting the reader
+ * never touched. The pair is dropped instead, and the next external run asks its caller for a
+ * pick.
+ */
+export declare function reconcileSubagentPair(config: Config): Config;
+export declare function validateMcpServer(value: unknown): McpServerConfig;
+/**
+ * Validate the installation's run bounds.
+ *
+ * A deadline-shaped bound accepts `0` as the explicit spelling of unlimited; every other
+ * value must be a positive safe integer, and a bound the runtime would reject must fail here
+ * instead of at the first run.
+ * @param limits - the configured limits block.
+ */
+export declare function validateLimitsConfig(limits: unknown): void;
+/**
+ * Read the configured run bounds as effective limits.
+ *
+ * Normalizes the explicit `0` spelling to an absent key, so the runtime only ever has to
+ * answer one question: is a bound set, or is the run unlimited?
+ * @param config - the loaded configuration.
+ * @returns partial limits ready to hand a run, empty when nothing is configured.
+ */
+export declare function resolveConfiguredLimits(config: Pick<Config, 'limits'>): Partial<Limits>;
+export declare function validateMemoryConfig(memory: unknown): void;
+/** Environment overrides win over config.json; nothing is persisted back. */
+export declare function resolveMemoryConfig(config: Config, env?: NodeJS.ProcessEnv): MemoryConfig;
+export declare function loadConfig(directory?: string): Promise<Config>;
+/**
+ * The anonymous-feedback preference this installation has saved right now.
+ *
+ * The setting belongs to the installation rather than to any one process: the desktop app and
+ * every CLI write the same file, so a process that started before the change holds a snapshot
+ * that no longer says what was saved. A reader that reports or changes the preference asks here
+ * for the file's own answer rather than for the snapshot it loaded at startup.
+ *
+ * Only the block is read, and it is validated on its own: a preference that cannot be stored is
+ * a file the user believes is doing something, and a reader must not answer from it.
+ * @param directory - the installation's configuration directory.
+ * @returns the saved block, or undefined when the file holds none.
+ */
+export declare function loadSavedAnalytics(directory?: string): Promise<AnalyticsConfig | undefined>;
+export declare function saveConfig(config: Config, directory?: string): Promise<void>;
+/** Raised when the stored configuration was replaced between a read and the write that followed it. */
+export declare class ConfigConflictError extends Error {
+    constructor();
+}
+/**
+ * Change the configuration file under the installation's lock, re-applying the change if it was replaced.
+ *
+ * The lock serializes every writer that honours it; the comparison covers the writers that cannot — an
+ * older installation, or a person editing the file — by re-applying the change to the newer content when
+ * the stored text is not the one this change was computed from. `change` has to be a pure function of the
+ * configuration it is given, which is what makes re-applying it safe.
+ */
+export declare function changeConfigFile(directory: string, change: (current: Config) => Config, attempts?: number): Promise<Config>;
+export declare function validateCodeIntelConfig(codeIntel: unknown): void;
+/** Code intelligence defaults to on; config.json can disable it globally or per repository. */
+export declare function resolveCodeIntelConfig(config: Config): Required<Pick<CodeIntelConfig, 'enabled'>> & CodeIntelConfig;
+/**
+ * Validate the Remote Workspace section.
+ *
+ * Device tokens, invitation tokens, and workspace credentials are 256-bit random values; the id
+ * shapes are what the pairing transaction generates. Rejecting anything else here means a
+ * hand-edited or corrupted file fails loudly at load instead of being presented as a live device
+ * or a redeemable invitation. Absolute share paths are deliberately NOT validated against any
+ * allowlist — the host chose them — but they must be plain filesystem paths with no control
+ * characters, because the browse layer treats them as containment roots.
+ */
+export declare function validateRemoteConfig(remote: unknown): void;
+/**
+ * Validate the project registry the rail and peers read.
+ *
+ * `path` is the realpath the registry stores (the entry key for idempotent adds), so it must be a
+ * plain absolute-ish filesystem path free of control characters; the name is a display label.
+ */
+export declare function validateProjectsConfig(projects: unknown): void;
+export declare function validateDecisionConfig(value: unknown): void;