vouchington-tooling 0.41.0 → 0.43.0

package/dist/mcp-server/retrospective-front-matter.mjs

@@ -0,0 +1,88 @@
+const KEYS = [
+    'date',
+    'issues',
+    'prs',
+    'session_id',
+    'description',
+    'work_outcome',
+    'feedback_coverage',
+    'repositories',
+];
+const isString = (value) => typeof value === 'string';
+const isStrings = (value) => Array.isArray(value) && value.every(isString);
+const isReference = (value) => (isString(value) && value.trim() !== '') || (Number.isSafeInteger(value) && value > 0);
+function fail(message) {
+    throw new Error(`retrospective front matter: ${message}`);
+}
+function parseLines(block) {
+    const values = new Map();
+    // composeRetrospective joins its sections with blank lines, so blank lines are allowed.
+    for (const line of block.split('\n').filter((candidate) => candidate !== '')) {
+        const separator = line.indexOf(': ');
+        const key = separator < 0 ? '' : line.slice(0, separator);
+        if (!KEYS.includes(key))
+            fail(separator < 0 || !/^[a-z_]+$/.test(key)
+                ? `malformed line ${JSON.stringify(line)}; each line is "key: <JSON value>"`
+                : `unknown key ${key}`);
+        if (values.has(key))
+            fail(`duplicate key ${key}`);
+        try {
+            values.set(key, JSON.parse(line.slice(separator + 2)));
+        }
+        catch {
+            fail(`${key} is not a JSON value`);
+        }
+    }
+    return values;
+}
+function coverageOf(coverage) {
+    if (typeof coverage !== 'object' ||
+        coverage === null ||
+        Object.keys(coverage).some((key) => !['status', 'sources', 'droppedCount'].includes(key)) ||
+        !isString(coverage.status) ||
+        !isStrings(coverage.sources) ||
+        !Number.isSafeInteger(coverage.droppedCount))
+        fail('feedback_coverage must be { status, sources, droppedCount }');
+    return coverage;
+}
+/**
+ * Parses the block from the leading `---` line to the next `---` line. Every line is
+ * `key: <JSON value>`; unknown keys, duplicates, malformed lines and ill-typed values are errors,
+ * and `date`, `issues`, and `prs` are required.
+ */
+export function parseRetrospectiveFrontMatter(markdown) {
+    const block = /^---\n([\s\S]*?)\n---(?:\n|$)/.exec(markdown.replaceAll('\r\n', '\n'))?.[1];
+    if (block === undefined)
+        fail('the document must start with a block between two "---" lines, as composeRetrospective writes');
+    const values = parseLines(block);
+    const { date, issues, prs } = Object.fromEntries(values);
+    if (!isString(date) || !/^\d{4}-\d{2}-\d{2}$/.test(date))
+        fail('date must be a YYYY-MM-DD string');
+    for (const [name, list] of [
+        ['issues', issues],
+        ['prs', prs],
+    ])
+        if (!Array.isArray(list) || !list.every(isReference))
+            fail(`${name} must be an array of positive integers or non-empty strings`);
+    const text = (key) => {
+        const value = values.get(key);
+        if (value !== undefined && !isString(value))
+            fail(`${key} must be a string`);
+        return value;
+    };
+    const repositories = values.get('repositories');
+    if (repositories !== undefined && !isStrings(repositories))
+        fail('repositories must be an array of strings');
+    const coverage = values.get('feedback_coverage');
+    const parsed = {
+        date,
+        issues: issues,
+        prs: prs,
+        sessionId: text('session_id'),
+        description: text('description'),
+        workOutcome: text('work_outcome'),
+        feedbackCoverage: coverage === undefined ? undefined : coverageOf(coverage),
+        repositories: repositories,
+    };
+    return Object.fromEntries(Object.entries(parsed).filter(([, value]) => value !== undefined));
+}

package/dist/mcp-server/retrospective-input.d.mts

@@ -0,0 +1,29 @@
+import { type FeedbackCoverage, type WorkOutcome } from '../agent-blackboard/index.mts';
+import type { BlackboardClientDependencies } from '../agent-blackboard/client.mts';
+import { type Args } from './args.mts';
+/** The longest a facts subprocess may run before it is killed. */
+export declare const FACTS_TIMEOUT_MS = 120000;
+type ComposeBase = {
+    sessionId: string;
+    repositories: string[];
+    workOutcome: WorkOutcome;
+    feedbackCoverage: FeedbackCoverage;
+    worktree: string;
+    env: NodeJS.ProcessEnv;
+    dependencies: BlackboardClientDependencies;
+};
+/**
+ * Facts commands run in the worktree and never see the blackboard credentials, NODE_OPTIONS, or
+ * GIT_* overrides that could point git away from the validated worktree.
+ */
+export declare function worktreeExecutor(worktree: string, env: NodeJS.ProcessEnv, timeoutMs?: number): (command: string, args: string[]) => Promise<{
+    ok: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+}>;
+/** The caller's `compose.knownSensitiveValues` plus the server's blackboard token, when set. */
+export declare function sensitiveValues(compose: Args | undefined, env: NodeJS.ProcessEnv): string[];
+/** Builds the retrospective markdown with `composeRetrospective`, rejecting unknown input keys. */
+export declare function composeFromArgs(compose: Args, base: ComposeBase): Promise<string>;
+export {};

package/dist/mcp-server/retrospective-input.mjs

@@ -0,0 +1,145 @@
+import { composeRetrospective, } from "../agent-blackboard/index.mjs";
+import { rejectUnknown } from "./args.mjs";
+import { inspectHarnessEnvironment, selectHarnessSession, } from "../agent-harness-identity/index.mjs";
+import { SESSION_ID } from "../retrospective-transcript/resolve-transcript-file.mjs";
+import { serverJournalLoader } from "./journal-read.mjs";
+import { checkFactsInput } from "./retrospective-facts-input.mjs";
+import { spawnPolicy } from "./policy-spawn.mjs";
+const HARNESSES = ['codex', 'claude', 'cursor', 'grok'];
+const COMPOSE_KEYS = [
+    'narrative',
+    'date',
+    'issues',
+    'prs',
+    'description',
+    'facts',
+    'transcript',
+    'tools',
+    'architecture',
+    'knownSensitiveValues',
+];
+const COMPOSE_REQUIRED = COMPOSE_KEYS.filter((key) => key !== 'knownSensitiveValues');
+/** No `repo`: a caller must not aim the server's GitHub token at another repository. */
+const FACTS_KEYS = ['pr', 'branch', 'noPr', 'status', 'reason'];
+/** No path overrides: the server reads the session's transcript from its own default roots. */
+const TRANSCRIPT_KEYS = ['sessionId', 'harnessSessionId', 'status', 'reason'];
+/** The longest a facts subprocess may run before it is killed. */
+export const FACTS_TIMEOUT_MS = 120_000;
+const MAX_OUTPUT_BYTES = 10_000_000;
+function section(compose, name, keys) {
+    const value = compose[name];
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        throw new Error(`compose.${name} must be an object`);
+    rejectUnknown(value, keys);
+    return value;
+}
+/**
+ * Facts commands run in the worktree and never see the blackboard credentials, NODE_OPTIONS, or
+ * GIT_* overrides that could point git away from the validated worktree.
+ */
+export function worktreeExecutor(worktree, env, timeoutMs = FACTS_TIMEOUT_MS) {
+    const safe = Object.fromEntries(Object.entries(env).filter(([name]) => !name.startsWith('AGENT_BLACKBOARD_') &&
+        !name.startsWith('GIT_') &&
+        name !== 'NODE_OPTIONS'));
+    // Each command runs in its own process group, killed whole when it exits or times out, so a
+    // helper that git or gh starts cannot outlive the call with an inherited GH_TOKEN.
+    return async (command, args) => {
+        let outcome;
+        try {
+            outcome = await spawnPolicy({
+                command,
+                args,
+                cwd: worktree,
+                env: safe,
+                input: '',
+                timeoutMs,
+                maxOutputBytes: MAX_OUTPUT_BYTES,
+            });
+        }
+        catch (error) {
+            return { ok: false, stdout: '', stderr: error.message, exitCode: null };
+        }
+        const { stdout, stderr, exitCode, timedOut, overflowed } = outcome;
+        if (timedOut || overflowed) {
+            const reason = timedOut
+                ? `timed out after ${timeoutMs} ms`
+                : `wrote more than ${MAX_OUTPUT_BYTES} bytes`;
+            return { ok: false, stdout, stderr: `${stderr}${command} ${reason}`, exitCode: null };
+        }
+        return { ok: exitCode === 0, stdout, stderr, exitCode };
+    };
+}
+/** The caller's `compose.knownSensitiveValues` plus the server's blackboard token, when set. */
+export function sensitiveValues(compose, env) {
+    const given = compose?.knownSensitiveValues;
+    if (given !== undefined && (!Array.isArray(given) || given.some((v) => typeof v !== 'string')))
+        throw new Error('compose.knownSensitiveValues must be an array of strings');
+    // Redaction ignores values under four characters, so promising to redact one would be false.
+    if (given?.some((value) => value.length < 4))
+        throw new Error('compose.knownSensitiveValues entries must be at least 4 characters');
+    // Facts commands inherit the GitHub tokens, so their output is redacted of those values too.
+    const credentials = [env.AGENT_BLACKBOARD_TOKEN, env.GH_TOKEN, env.GITHUB_TOKEN].filter((value) => Boolean(value));
+    const values = [...(given ?? []), ...credentials];
+    // The composer JSON-escapes structured fields, so each value is also redacted in that form.
+    const escaped = values.map((value) => JSON.stringify(value).slice(1, -1));
+    // Longest first, so a shorter value that is a prefix of a credential cannot break its match.
+    return [...new Set([...values, ...escaped])].sort((a, b) => b.length - a.length);
+}
+/**
+ * The transcript collector input: the server's worktree and default session roots only. A caller
+ * may name the session (it must be this one), give the harness's own UUID session id when the
+ * blackboard session id is not one, or report the transcript as unassessed.
+ */
+function transcriptInput(transcript, base) {
+    if ('status' in transcript) {
+        if ('sessionId' in transcript || 'harnessSessionId' in transcript)
+            throw new Error('compose.transcript: sessionId and harnessSessionId are exclusive with status');
+        return transcript;
+    }
+    // A reason without a status is malformed, not a request to read the transcript.
+    if ('reason' in transcript)
+        throw new Error('compose.transcript.reason requires a status');
+    if (transcript.sessionId !== undefined && transcript.sessionId !== base.sessionId)
+        throw new Error('compose.transcript.sessionId must equal the sessionId of the call');
+    const harnessId = transcript.harnessSessionId ?? base.sessionId;
+    // Transcripts are found by the harness's UUID; never let a lookup fail into "unavailable".
+    if (typeof harnessId !== 'string' || !SESSION_ID.test(harnessId))
+        throw new Error('compose.transcript needs a UUID session id: pass harnessSessionId (the harness session ' +
+            'UUID) or { status, reason }');
+    // When the harness that launched the server names its session, no other transcript is read.
+    const own = selectHarnessSession(inspectHarnessEnvironment(base.env), HARNESSES)?.sessionId;
+    if (own !== undefined && own.toLowerCase() !== harnessId.toLowerCase())
+        // A server can outlive its session (Claude Code /clear, a Codex thread switch).
+        throw new Error('compose.transcript may read only the harness session that launched the server: if the ' +
+            'session changed since (/clear, a thread switch), reconnect the server (/mcp in Claude ' +
+            'Code, or restart Codex), or pass { status, reason }');
+    return { sessionId: harnessId, cwd: base.worktree };
+}
+function factsInput(facts, base) {
+    return checkFactsInput(facts)
+        ? { ...facts, execute: worktreeExecutor(base.worktree, base.env) }
+        : facts;
+}
+/** Builds the retrospective markdown with `composeRetrospective`, rejecting unknown input keys. */
+export async function composeFromArgs(compose, base) {
+    rejectUnknown(compose, COMPOSE_KEYS);
+    const missing = COMPOSE_REQUIRED.filter((key) => compose[key] === undefined);
+    if (missing.length)
+        throw new Error(`compose is missing: ${missing.join(', ')}`);
+    if (typeof compose.narrative !== 'string' || !compose.narrative.trim())
+        throw new Error('compose.narrative must be a non-empty string');
+    const facts = section(compose, 'facts', FACTS_KEYS);
+    const transcript = section(compose, 'transcript', TRANSCRIPT_KEYS);
+    const input = {
+        ...compose,
+        sessionId: base.sessionId,
+        repositories: base.repositories,
+        workOutcome: base.workOutcome,
+        feedbackCoverage: base.feedbackCoverage,
+        facts: factsInput(facts, base),
+        transcript: transcriptInput(transcript, base),
+        knownSensitiveValues: sensitiveValues(compose, base.env),
+        journal: { journalLoader: serverJournalLoader(base.env, base.dependencies) },
+    };
+    return composeRetrospective(input);
+}

package/dist/mcp-server/retrospective-resolve.d.mts

@@ -0,0 +1,15 @@
+import type { FeedbackCoverage } from '../agent-blackboard/index.mts';
+import { type PolicyRun } from './policy-run.mts';
+import type { RetrospectiveFrontMatter } from './retrospective-front-matter.mts';
+/** Rejects, naming the field, any argument the document's own front matter contradicts. */
+export declare function checkFrontMatter(front: RetrospectiveFrontMatter, args: {
+    sessionId: string;
+    workOutcome: string;
+    feedbackCoverage: FeedbackCoverage;
+    repositories: string[] | undefined;
+}): void;
+/**
+ * The canonical (sorted, deduplicated, lowercase) repositories: the argument, else the
+ * document's front matter, else the policy's `pullRequestDefaults().repositories`, else an error.
+ */
+export declare function resolveRepositories(args: string[] | undefined, front: string[] | undefined, policy: Omit<PolicyRun, 'export' | 'input'>): Promise<string[]>;

package/dist/mcp-server/retrospective-resolve.mjs

@@ -0,0 +1,41 @@
+import { normalizeRepositories } from "../agent-blackboard/feedback-codec.mjs";
+import { runPolicyExport } from "./policy-run.mjs";
+const same = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+/** Rejects, naming the field, any argument the document's own front matter contradicts. */
+export function checkFrontMatter(front, args) {
+    const mismatches = [];
+    if (front.sessionId !== undefined && front.sessionId !== args.sessionId)
+        mismatches.push('session_id does not match sessionId');
+    if (front.workOutcome !== undefined && front.workOutcome !== args.workOutcome)
+        mismatches.push('work_outcome does not match workOutcome');
+    if (front.feedbackCoverage !== undefined) {
+        // Field by field, so the document's JSON key order does not matter; sources stay ordered.
+        const { status, sources, droppedCount } = args.feedbackCoverage;
+        const given = front.feedbackCoverage;
+        if (given.status !== status ||
+            given.droppedCount !== droppedCount ||
+            !same(given.sources, sources))
+            mismatches.push('feedback_coverage does not match feedbackCoverage');
+    }
+    if (front.repositories !== undefined &&
+        args.repositories !== undefined &&
+        !same(normalizeRepositories(front.repositories), normalizeRepositories(args.repositories)))
+        mismatches.push('repositories does not match repositories');
+    if (mismatches.length)
+        throw new Error(`retrospective front matter contradicts the arguments: ${mismatches.join('; ')}`);
+}
+/**
+ * The canonical (sorted, deduplicated, lowercase) repositories: the argument, else the
+ * document's front matter, else the policy's `pullRequestDefaults().repositories`, else an error.
+ */
+export async function resolveRepositories(args, front, policy) {
+    const given = args ?? front;
+    if (given !== undefined)
+        return normalizeRepositories(given);
+    const defaults = await runPolicyExport({ ...policy, export: 'pullRequestDefaults', input: {} });
+    const repositories = (defaults.status === 'ok' ? defaults.result : undefined);
+    if (Array.isArray(repositories?.repositories) && repositories.repositories.length)
+        return normalizeRepositories(repositories.repositories);
+    throw new Error('repositories is required: pass it, put it in the front matter, or have the policy ' +
+        'pullRequestDefaults export return { repositories }');
+}

package/dist/mcp-server/tools-pr.d.mts

@@ -0,0 +1,2 @@
+import { type ToolDefinition } from './tools-schema.mts';
+export declare const PR_TOOLS: readonly ToolDefinition[];

package/dist/mcp-server/tools-pr.mjs

@@ -0,0 +1,69 @@
+import { ADDITIVE, MUTATING, READ_ONLY, tool, } from "./tools-schema.mjs";
+/** These tools read or write GitHub, outside the server's own state. */
+const openWorld = (annotations) => ({
+    ...annotations,
+    openWorldHint: true,
+});
+const text = (description) => ({ type: 'string', minLength: 1, description });
+const PR_NUMBER = { type: 'integer', minimum: 1, description: 'Pull request number.' };
+const FIELDS = {
+    title: { type: 'string', minLength: 1, maxLength: 256, description: 'Single-line PR title.' },
+    summary: text('What the change does, as markdown.'),
+    impact: text('Who or what is affected, as markdown.'),
+    relatedIssues: {
+        type: 'array',
+        description: 'Issues this pull request closes or refs; may be empty.',
+        items: {
+            type: 'object',
+            properties: {
+                number: { type: 'integer', minimum: 1 },
+                relation: { enum: ['closes', 'refs'] },
+                reason: text('Why the issue is related.'),
+            },
+            required: ['number', 'relation', 'reason'],
+            additionalProperties: false,
+        },
+    },
+    details: {
+        type: 'array',
+        minItems: 1,
+        items: { type: 'string', minLength: 1 },
+        description: 'Markdown paragraphs or bullets, joined by blank lines.',
+    },
+    base: { type: 'string', minLength: 1, description: 'Base branch. Default: main.' },
+    agent: text('Agent name for the Agent line.'),
+    model: text('Optional model name, rendered in parentheses after the agent.'),
+    mode: { enum: ['interactive', 'autonomous'], description: 'Delivery mode, given to the policy.' },
+    workspaceSetup: text('Text for the Workspace setup line, such as how the worktree was prepared.'),
+};
+const REQUIRED = [
+    'title',
+    'summary',
+    'impact',
+    'relatedIssues',
+    'details',
+    'agent',
+    'mode',
+    'workspaceSetup',
+];
+const RENDERING = 'The server renders the body from the structured input (Summary, Impact, Related issues, ' +
+    'Details, then Workspace setup, Agent, Device and Worktree lines) and runs the checkout ' +
+    'policy validatePullRequest export in a child process; the head branch is the ' +
+    "worktree's current branch. Policy tools need a server launched inside a repository worktree. ";
+export const PR_TOOLS = [
+    tool('pr_validate', 'Renders the pull request body and validates it with the checkout policy; writes nothing. ' +
+        RENDERING +
+        'Pass pr to validate an update of that pull request: the live body is read and its Shepherd ' +
+        'Journal preserved. Returns { body, errors, warnings }.', openWorld(READ_ONLY), { ...FIELDS, pr: PR_NUMBER }, REQUIRED),
+    tool('pr_create', 'Creates a draft pull request from the worktree branch. ' +
+        RENDERING +
+        'Validation errors block creation. The policy pullRequestDefaults export may add labels, a ' +
+        'milestone and a project. The branch must already be pushed and current. It sees no stack ' +
+        'membership, so a policy may reject a non-default base; create stacked layers with the ' +
+        "repository's stack tooling. Returns { number, url, warnings }.", openWorld(ADDITIVE), FIELDS, REQUIRED),
+    tool('pr_update', "Replaces an open pull request's title and body. " +
+        RENDERING +
+        "The pull request's head branch must be the worktree branch. The live Shepherd Journal is " +
+        'preserved and nothing else is carried over from the live body. Validation errors block ' +
+        'the update. Returns { number, url, warnings }.', openWorld(MUTATING), { ...FIELDS, pr: PR_NUMBER }, [...REQUIRED, 'pr']),
+];

package/dist/mcp-server/tools-retrospective.d.mts

@@ -0,0 +1,2 @@
+import { type ToolDefinition } from './tools-schema.mts';
+export declare const RETROSPECTIVE_TOOLS: readonly ToolDefinition[];

package/dist/mcp-server/tools-retrospective.mjs

@@ -0,0 +1,48 @@
+import { ADDITIVE, COVERAGE, IDENTITY, IDENTITY_REQUIRED, ID_PATTERN, OUTCOMES, READ_ONLY, tool, } from "./tools-schema.mjs";
+export const RETROSPECTIVE_TOOLS = [
+    tool('retrospective_check', 'Reports whether the session already holds a retrospective: { sessionId, saved, entries } ' +
+        'where each entry is { sourceEventId, timestamp, issues, prs } for an entry of type ' +
+        'retrospective, oldest first. sourceEventId narrows the result. A session that was never ' +
+        'created reports saved: false.', READ_ONLY, { sourceEventId: { type: 'string', pattern: ID_PATTERN, description: 'Only this event id.' } }),
+    tool('retrospective_save', 'Saves the session retrospective after the checkout policy accepts it, and returns the same ' +
+        'verified receipt as journal_append (status, receipt, timestamp, pendingCount, ' +
+        'worktreePendingCount) plus policy.warnings. Pass exactly one of markdown (a finished ' +
+        'document opening with the front matter composeRetrospective writes: date, issues, prs ' +
+        'and optionally session_id, description, work_outcome, feedback_coverage, repositories, ' +
+        'each line key: <JSON>; any that repeat an argument must equal it) or compose (the retrospective ' +
+        'composer input: narrative, date, issues, prs, description, facts, transcript, tools, ' +
+        'architecture, optional knownSensitiveValues; the server adds the rest). compose.transcript ' +
+        'takes only { sessionId?, harnessSessionId? } (sessionId must be the call sessionId; the ' +
+        'transcript is found by harnessSessionId, the harness session UUID, else by sessionId when ' +
+        'that is a UUID, in the default session roots of the worktree) or { status, reason } to report it ' +
+        'unassessed; any path override is rejected. The server redacts its blackboard token ' +
+        'from the document before the policy sees it. dryRun returns ' +
+        '{ markdown, policy: { warnings } } and writes nothing. The worktree package.json may ' +
+        'declare "vouchington-tooling": { "policy": "<module>" }; its validateRetrospective export ' +
+        'runs in a child process, and any error it reports rejects the save with nothing written. ' +
+        'Policy tools need a server launched inside a repository worktree. The server owns the ' +
+        'timestamp. sourceEventId defaults to retrospective-<sessionId> (retrospective-<sha256 hex of the ' +
+        'sessionId> when that exceeds 256 bytes); saving changed content ' +
+        'under the same sourceEventId is an event-conflict, so a revision needs a new ' +
+        'sourceEventId. Repeat an identical markdown call to retry. compose regenerates the document, ' +
+        'so deliver a retained compose save with outbox_flush instead of repeating it. Counts ' +
+        'follow journal_append.', ADDITIVE, {
+        ...IDENTITY,
+        mode: { enum: ['interactive', 'autonomous'], description: 'Delivery mode.' },
+        workOutcome: { enum: OUTCOMES, description: 'Outcome of the work being reported.' },
+        feedbackCoverage: COVERAGE,
+        repositories: {
+            type: 'array',
+            items: { type: 'string' },
+            minItems: 1,
+            description: 'Exact owner/name repositories; stored sorted, deduplicated and lowercase. Default: ' +
+                'the front matter repositories, else the policy pullRequestDefaults repositories; ' +
+                'an error when none.',
+        },
+        markdown: { type: 'string', description: 'Finished retrospective markdown.' },
+        compose: { type: 'object', description: 'Composer input; exclusive with markdown.' },
+        sourceEventId: { type: 'string', pattern: ID_PATTERN, description: 'Stable event id.' },
+        category: { type: 'string', description: 'Optional context; never changes entry type.' },
+        dryRun: { type: 'boolean', description: 'Compose and validate only; write nothing.' },
+    }, [...IDENTITY_REQUIRED, 'mode', 'workOutcome', 'feedbackCoverage']),
+];

package/dist/mcp-server/tools-schema.d.mts

@@ -0,0 +1,54 @@
+export type JsonSchema = Record<string, unknown>;
+export type ToolDefinition = {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, JsonSchema>;
+        required: string[];
+        additionalProperties: false;
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare const ID_PATTERN = "^[A-Za-z0-9._:-]+$";
+export declare const PARENT_SESSION_ID: JsonSchema;
+export declare const AGENT: JsonSchema;
+export declare const VERSION: JsonSchema;
+export declare const OUTCOMES: string[];
+export declare const COVERAGE: JsonSchema;
+export declare const READ_ONLY: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export declare const ADDITIVE: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export declare const IDEMPOTENT_ADDITIVE: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export declare const MUTATING: {
+    readOnlyHint: boolean;
+    destructiveHint: boolean;
+    idempotentHint: boolean;
+    openWorldHint: boolean;
+};
+export declare function tool(name: string, description: string, annotations: ToolDefinition['annotations'], properties?: Record<string, JsonSchema>, required?: string[]): ToolDefinition;
+export declare const IDENTITY: {
+    parentSessionId: JsonSchema;
+    agent: JsonSchema;
+    version: JsonSchema;
+};
+export declare const IDENTITY_REQUIRED: string[];

package/dist/mcp-server/tools-schema.mjs

@@ -0,0 +1,70 @@
+export const ID_PATTERN = '^[A-Za-z0-9._:-]+$';
+const SESSION_ID = {
+    type: 'string',
+    pattern: ID_PATTERN,
+    maxLength: 256,
+    description: 'Explicit session id (URL-safe). Never inferred by the server.',
+};
+const WORKTREE = {
+    type: 'string',
+    description: 'Absolute path of the top level of a git worktree (`git rev-parse --show-toplevel`), not a ' +
+        'subdirectory. Defaults to the launch directory worktree; required when the server was ' +
+        'launched outside a git worktree.',
+};
+export const PARENT_SESSION_ID = {
+    type: ['string', 'null'],
+    pattern: ID_PATTERN,
+    maxLength: 256,
+    description: 'Direct parent session id, or null for a root session.',
+};
+export const AGENT = { type: 'string', maxLength: 128, description: 'Agent name.' };
+export const VERSION = { type: 'string', maxLength: 128, description: 'Agent version.' };
+export const OUTCOMES = [
+    'in-progress',
+    'success',
+    'failure',
+    'cancelled',
+    'timed-out',
+    'no-change',
+    'policy-refusal',
+    'unknown',
+];
+const COVERAGE_STATUSES = ['complete', 'partial', 'unavailable', 'not-assessed', 'not-started'];
+export const COVERAGE = {
+    type: 'object',
+    properties: {
+        status: { enum: COVERAGE_STATUSES },
+        sources: { type: 'array', items: { type: 'string' } },
+        droppedCount: { type: 'integer', minimum: 0 },
+    },
+    required: ['status'],
+    additionalProperties: false,
+    description: 'Explicit coverage; sources default to [] and droppedCount to 0.',
+};
+export const READ_ONLY = flags(true, false, true);
+export const ADDITIVE = flags(false, false, false);
+export const IDEMPOTENT_ADDITIVE = flags(false, false, true);
+export const MUTATING = flags(false, true, true);
+function flags(readOnly, destructive, idempotent) {
+    return {
+        readOnlyHint: readOnly,
+        destructiveHint: destructive,
+        idempotentHint: idempotent,
+        openWorldHint: false,
+    };
+}
+export function tool(name, description, annotations, properties = {}, required = []) {
+    return {
+        name,
+        description,
+        inputSchema: {
+            type: 'object',
+            properties: { sessionId: SESSION_ID, worktree: WORKTREE, ...properties },
+            required: ['sessionId', ...required],
+            additionalProperties: false,
+        },
+        annotations,
+    };
+}
+export const IDENTITY = { parentSessionId: PARENT_SESSION_ID, agent: AGENT, version: VERSION };
+export const IDENTITY_REQUIRED = ['parentSessionId', 'agent', 'version'];

package/dist/mcp-server/tools.d.mts

@@ -1,19 +1,2 @@
-type JsonSchema = Record<string, unknown>;
-export type ToolDefinition = {
-    name: string;
-    description: string;
-    inputSchema: {
-        type: 'object';
-        properties: Record<string, JsonSchema>;
-        required: string[];
-        additionalProperties: false;
-    };
-    annotations: {
-        readOnlyHint: boolean;
-        destructiveHint: boolean;
-        idempotentHint: boolean;
-        openWorldHint: boolean;
-    };
-};
+import { type ToolDefinition } from './tools-schema.mts';
 export declare const TOOLS: readonly ToolDefinition[];
-export {};