@zergai/ztc 0.4.0-beta.1 → 0.5.0-beta.1

package/dist/router_auth.d.ts

@@ -2,6 +2,9 @@ import type { ZTCAuthMode } from './config/types.js';
 export declare const DEFAULT_ROUTER_ORIGIN = "https://zergrouter.com";
 /** Local, actionable routing failures whose messages contain no remote payload. */
 export declare class RouterConfigurationError extends Error {
+    readonly kind: 'configuration' | 'expired' | 'authentication_required';
+    constructor(message: string, kind?: 'configuration' | 'expired' | 'authentication_required');
+    get needsSignIn(): boolean;
 }
 type RouterAuthOutput = (message: string, stream: 'stdout' | 'stderr') => void;
 export interface RouterCredentials {
@@ -16,6 +19,34 @@ export interface RouterCredentials {
     };
 }
 export declare function loadRouterCredentials(): Promise<RouterCredentials | null>;
+export interface RouterAccountReadiness {
+    version: 1;
+    scope: {
+        kind: 'personal';
+        accountId: string;
+    };
+    funding: {
+        state: 'ready' | 'needs_payment' | 'payment_pending' | 'payment_failed' | 'cap_reached' | 'unavailable';
+        mode: 'live' | 'test' | 'unknown';
+        source: 'paid' | 'trial' | null;
+        remainingUsd: string | null;
+        capUsd: string | null;
+        trialTokensRemaining: number | null;
+    };
+    model: {
+        provider: 'modal';
+        id: 'deepseek-v4.1-flash';
+        available: boolean;
+    };
+    ready: boolean;
+    nextAction: 'start' | 'billing' | 'wait_for_payment' | 'retry' | 'select_model';
+    links: {
+        billing: string;
+        signIn: string;
+    };
+}
+export declare function readRouterAccountReadiness(credentials: RouterCredentials): Promise<RouterAccountReadiness>;
+export declare function formatRouterAccountReadiness(account: RouterAccountReadiness): string;
 /** Shared Router authentication for the shell and in-session slash commands. */
 export declare function runRouterAuthCommand(args: readonly string[], output?: RouterAuthOutput): Promise<void>;
 export {};

package/dist/router_auth.js

@@ -1,14 +1,22 @@
 import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { chmod, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import { hostname } from 'node:os';
-import { join } from 'node:path';
+import { dirname, join } from 'node:path';
 import { spawn } from 'node:child_process';
 import { setTimeout as delay } from 'node:timers/promises';
 import { getVersion } from './utils/version.js';
-import { profileConfigDir } from './config/profiles.js';
+import { activeProfile, profileConfigDir } from './config/profiles.js';
 export const DEFAULT_ROUTER_ORIGIN = 'https://zergrouter.com';
 /** Local, actionable routing failures whose messages contain no remote payload. */
 export class RouterConfigurationError extends Error {
+    kind;
+    constructor(message, kind = 'configuration') {
+        super(message);
+        this.kind = kind;
+    }
+    get needsSignIn() {
+        return this.kind === 'expired' || this.kind === 'authentication_required';
+    }
 }
 const terminalOutput = (message, stream) => { process[stream].write(message); };
 function credentialDirectory() {
@@ -81,12 +89,13 @@ export async function loadRouterCredentials() {
     }
 }
 async function saveCredentials(credentials) {
-    await mkdir(credentialDirectory(), { recursive: true, mode: 0o700 });
-    const temporary = `${credentialPath()}.${randomUUID()}.tmp`;
+    const path = credentialPath();
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const temporary = `${path}.${randomUUID()}.tmp`;
     try {
         await writeFile(temporary, JSON.stringify(credentials) + '\n', { mode: 0o600, flag: 'wx' });
         await chmod(temporary, 0o600);
-        await rename(temporary, credentialPath());
+        await rename(temporary, path);
     }
     finally {
         await unlink(temporary).catch(error => {
@@ -119,7 +128,34 @@ async function request(origin, path, body, token, method) {
         signal: AbortSignal.timeout(15_000),
         redirect: 'error',
     });
-    const value = await response.json().catch(() => null);
+    let value = null;
+    const reader = response.body?.getReader();
+    if (reader) {
+        const chunks = [];
+        let size = 0;
+        try {
+            for (;;) {
+                const { done, value: chunk } = await reader.read();
+                if (done)
+                    break;
+                size += chunk.byteLength;
+                if (size > 32_768) {
+                    await reader.cancel();
+                    throw new Error('Router returned an invalid oversized response.');
+                }
+                chunks.push(chunk);
+            }
+            try {
+                value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            }
+            catch {
+                value = null;
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
     if (!response.ok) {
         const failure = value && typeof value === 'object' ? value : {};
         const nested = failure.data && typeof failure.data === 'object' ? failure.data : {};
@@ -129,6 +165,67 @@ async function request(origin, path, body, token, method) {
     }
     return record(value);
 }
+function validateReadiness(value, credentials) {
+    const invalid = () => new Error('Router returned invalid account readiness. Retry ztc auth readiness.');
+    const scope = record(value.scope);
+    const funding = record(value.funding);
+    const model = record(value.model);
+    const links = record(value.links);
+    const states = ['ready', 'needs_payment', 'payment_pending', 'payment_failed', 'cap_reached', 'unavailable'];
+    const actions = ['start', 'billing', 'wait_for_payment', 'retry', 'select_model'];
+    const money = (amount) => amount === null || typeof amount === 'string' && /^\d{1,15}(?:\.\d{1,12})?$/.test(amount);
+    if (value.version !== 1 || scope.kind !== 'personal' || scope.accountId !== credentials.workspaceId
+        || typeof funding.state !== 'string' || !states.includes(funding.state)
+        || typeof funding.mode !== 'string' || !['live', 'test', 'unknown'].includes(funding.mode)
+        || !['paid', 'trial', null].includes(funding.source) || !money(funding.remainingUsd) || !money(funding.capUsd)
+        || !(funding.trialTokensRemaining === null || Number.isSafeInteger(funding.trialTokensRemaining) && Number(funding.trialTokensRemaining) >= 0)
+        || model.provider !== 'modal' || model.id !== 'deepseek-v4.1-flash' || typeof model.available !== 'boolean'
+        || typeof value.ready !== 'boolean' || typeof value.nextAction !== 'string' || !actions.includes(value.nextAction))
+        throw invalid();
+    const expectedBilling = `${credentials.origin}/dashboard/billing`;
+    const expectedSignIn = `${credentials.origin}/api/auth/zerg/start?next=%2Fdashboard%2Fbilling`;
+    if (links.billing !== expectedBilling || links.signIn !== expectedSignIn
+        || value.ready !== (funding.state === 'ready' && model.available) || (value.ready && value.nextAction !== 'start'))
+        throw invalid();
+    return { version: 1, scope: { kind: 'personal', accountId: credentials.workspaceId },
+        funding: { state: funding.state, mode: funding.mode, source: funding.source, remainingUsd: funding.remainingUsd, capUsd: funding.capUsd, trialTokensRemaining: funding.trialTokensRemaining },
+        model: { provider: 'modal', id: 'deepseek-v4.1-flash', available: model.available }, ready: value.ready,
+        nextAction: value.nextAction, links: { billing: expectedBilling, signIn: expectedSignIn } };
+}
+export async function readRouterAccountReadiness(credentials) {
+    if (Date.parse(credentials.expiresAt) <= Date.now())
+        throw new RouterConfigurationError('Router session expired. Run ztc auth login again; verify your email in the browser before approving the device.', 'expired');
+    try {
+        return validateReadiness(await request(credentials.origin, '/api/cli/account/readiness', undefined, credentials.token), credentials);
+    }
+    catch (error) {
+        if (error instanceof RouterAuthError && [401, 403].includes(error.status))
+            throw new RouterConfigurationError('Router authorization needs renewal. Run ztc auth login, finish email verification in the browser, then retry ztc auth readiness.', 'authentication_required');
+        throw error;
+    }
+}
+export function formatRouterAccountReadiness(account) {
+    const funding = account.funding;
+    const lines = [`Personal Router account (${funding.mode} billing).`];
+    if (funding.state === 'ready')
+        lines.push(`${funding.source === 'trial' ? 'Trial' : 'Pay-as-you-go'} allowance remaining: $${funding.remainingUsd}.`);
+    else if (funding.state === 'payment_pending')
+        lines.push('Payment confirmation is pending. Wait for the browser billing page to confirm, then run ztc auth readiness again.');
+    else if (funding.state === 'payment_failed')
+        lines.push('Billing reports an outstanding or rejected payment. Run ztc auth billing to review it.');
+    else if (funding.state === 'cap_reached')
+        lines.push('Your account or API-key spending cap is reached. Review account billing and key caps in the browser before retrying.');
+    else if (funding.state === 'needs_payment')
+        lines.push('Set up personal pay-as-you-go funding: ztc auth billing. Confirm pricing and your spending cap in the browser; sign-in alone does not enable billing.');
+    else
+        lines.push('Funding readiness is temporarily unavailable. Review ztc auth billing, then retry ztc auth readiness.');
+    if (account.ready)
+        lines.push('Default model available: DeepSeek Flash. Start ZTC and enter your first task; /plan "Map this project." is a useful start. Your current model and provider settings are preserved.');
+    else if (funding.state === 'ready' && !account.model.available)
+        lines.push('DeepSeek Flash is temporarily unavailable. Run /models to choose an available model, or retry ztc auth readiness.');
+    lines.push('This check makes no model request. Optional bounded health check: /setup --check-agent (confirm before it uses quota).');
+    return lines.join('\n') + '\n';
+}
 function openBrowser(url, output) {
     const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'rundll32' : 'xdg-open';
     const args = process.platform === 'win32' ? ['url.dll,FileProtocolHandler', url] : [url];
@@ -137,6 +234,12 @@ function openBrowser(url, output) {
     child.unref();
 }
 async function login(origin, noBrowser, output) {
+    const profile = activeProfile();
+    const directory = profileConfigDir();
+    const assertOwner = () => {
+        if (activeProfile() !== profile || profileConfigDir() !== directory)
+            throw new Error('Router login cancelled: profile changed during browser approval. Run /auth login in the selected profile.');
+    };
     // A failed/denied attempt leaves an existing session intact.
     const existing = await loadRouterCredentials().catch(() => null);
     const deviceFingerprint = existing?.origin === origin ? existing.deviceFingerprint : randomUUID();
@@ -168,11 +271,14 @@ async function login(origin, noBrowser, output) {
         await delay(Math.min(interval * 1_000, deadline - Date.now()));
         if (Date.now() >= deadline)
             break;
+        assertOwner();
         try {
             const issued = await request(origin, '/api/cli/device/exchange', { grant_id: grantId, code_verifier: verifier });
+            assertOwner();
             const { ConfigStore } = await import('./config.js');
             const config = new ConfigStore();
             await config.load();
+            assertOwner();
             const current = config.get();
             // A repeated login must retain the settings from before the first login.
             const previousConfig = existing?.previousConfig && current.zergProxyUrl === existing.origin
@@ -190,6 +296,7 @@ async function login(origin, noBrowser, output) {
             if (Date.parse(credentials.expiresAt) <= Date.now())
                 throw new Error('Router returned an expired session.');
             await saveCredentials(credentials);
+            assertOwner();
             config.setGlobal('zergProxyUrl', origin);
             config.setGlobal('authMode', authMode);
             await config.save();
@@ -197,6 +304,16 @@ async function login(origin, noBrowser, output) {
             output(authMode === 'auto'
                 ? 'Routing: auto (Router while available, otherwise direct-provider authentication). Logout restores your previous settings.\n'
                 : 'Routing: zrouter (Router authentication required). Logout restores your previous settings.\n', 'stderr');
+            try {
+                const readiness = await readRouterAccountReadiness(credentials);
+                assertOwner();
+                output(formatRouterAccountReadiness(readiness), 'stderr');
+            }
+            catch {
+                // Account metadata availability cannot undo a completed device login.
+                if (activeProfile() === profile && profileConfigDir() === directory)
+                    output('Signed in. Check personal funding with ztc auth readiness; open ztc auth billing to review pay-as-you-go pricing and caps. No model request was made.\n', 'stderr');
+            }
             return;
         }
         catch (error) {
@@ -209,13 +326,13 @@ async function login(origin, noBrowser, output) {
             throw error;
         }
     }
-    throw new Error('Router login expired. Run ztc auth login again.');
+    throw new Error('Router login expired. Finish signup and email verification in your browser, then run ztc auth login again.');
 }
 /** Shared Router authentication for the shell and in-session slash commands. */
 export async function runRouterAuthCommand(args, output = terminalOutput) {
     const [action, ...options] = args;
     if (action === 'login') {
-        let origin = DEFAULT_ROUTER_ORIGIN;
+        let origin;
         let noBrowser = false;
         for (let i = 0; i < options.length; i++) {
             if (options[i] === '--no-browser')
@@ -225,11 +342,40 @@ export async function runRouterAuthCommand(args, output = terminalOutput) {
             else
                 throw new Error('Usage: ztc auth login [--url <router-origin>] [--no-browser]');
         }
+        if (!origin) {
+            // Shell and slash-command login share the active profile and URL overrides.
+            const { ConfigStore } = await import('./config.js');
+            const config = new ConfigStore();
+            await config.load();
+            origin = routerOrigin(config.get().zergProxyUrl ?? DEFAULT_ROUTER_ORIGIN);
+        }
         await login(origin, noBrowser, output);
         return;
     }
+    if (action === 'readiness' || action === 'billing') {
+        if (options.some(option => option !== (action === 'readiness' ? '--json' : '--no-browser')))
+            throw new Error(`Usage: ztc auth ${action} ${action === 'readiness' ? '[--json]' : '[--no-browser]'}`);
+        const profile = activeProfile();
+        const directory = profileConfigDir();
+        const credentials = await loadRouterCredentials();
+        if (action === 'billing') {
+            const url = `${credentials?.origin ?? DEFAULT_ROUTER_ORIGIN}/dashboard/billing`;
+            output(`Review personal pay-as-you-go pricing, payment status and your spending cap in the browser:\n${url}\nThen run ztc auth readiness.\n`, 'stdout');
+            if (!options.includes('--no-browser'))
+                openBrowser(url, output);
+        }
+        else {
+            if (!credentials)
+                throw new RouterConfigurationError('Sign in first: ztc auth login. Complete signup and email verification in the browser, then approve this device.', 'authentication_required');
+            const readiness = await readRouterAccountReadiness(credentials);
+            if (activeProfile() !== profile || profileConfigDir() !== directory)
+                throw new Error('Profile changed while checking readiness. Retry in the selected profile.');
+            output(options.includes('--json') ? JSON.stringify(readiness) + '\n' : formatRouterAccountReadiness(readiness), 'stdout');
+        }
+        return;
+    }
     if (action !== 'status' && action !== 'logout')
-        throw new Error('Usage: ztc auth <login|status|logout>');
+        throw new Error('Usage: ztc auth <login|status|readiness|billing|logout>');
     if (options.some(option => option !== (action === 'status' ? '--json' : '--local-only'))) {
         throw new Error(`Usage: ztc auth ${action} ${action === 'status' ? '[--json]' : '[--local-only]'}`);
     }

package/dist/runbooks/catalog.d.ts

@@ -0,0 +1,3 @@
+import type { RunbookPackage } from './package.js';
+/** Bundled data is compiled with core; scripts use only the existing workflow language. */
+export declare const bundledRunbooks: readonly RunbookPackage[];

package/dist/runbooks/catalog.js

@@ -0,0 +1,26 @@
+const readers = ['read_file', 'Read'];
+const commands = ['run_command', 'Bash', 'exec_command', 'shell_command'];
+const jobs = [
+    ['repo-orientation', 'Repo orientation', 'Map entrypoints, architecture and targeted checks from repository evidence. Read project instructions first. Return source-linked findings and unknowns; do not edit the repository.', ['Architecture map with source paths', 'Documented development and test commands']],
+    ['pr-review', 'PR review', 'Review the requested diff against surrounding code and project instructions. Identify concrete defects with source references, reproduce narrow failures where possible, and distinguish observations from hypotheses. Return recommendations for specialized review skills to the parent session when needed.', ['Reviewed source revision and diff scope', 'Prioritized findings with reproduction evidence']],
+    ['qa-gate', 'QA gate', 'Identify the project-specific verification gate. Run only the relevant existing checks through managed command tools, retain command outcomes and source revisions, and report failed, skipped or unavailable checks explicitly. Do not repair unrelated failures in this run.', ['Source-bound command outcomes', 'Pass/fail/skip verdict with limitations']],
+    ['deploy', 'Deploy', 'Prepare the deployment for the requested target. Inspect its runbook, credentials prerequisites and rollback plan without exposing credentials. Verify build and test evidence. Return missing inputs and consequential deployment approval requirements to the parent session before execution; the runbook installation itself grants no execution authority.', ['Deployment target and proposed steps', 'Verification, approval and rollback evidence']],
+    ['incident-triage', 'Incident triage', 'Inspect the specified incident scope and available logs using the current session tools. Establish a timeline, impacted surface and evidence-backed hypotheses. Propose a bounded next step and return missing authorization to the parent session before recovery actions. Do not reset or alter unrelated services.', ['Incident timeline and source-linked observations', 'Proposed recovery with uncertainty and ownership']],
+    ['onboarding', 'Onboarding', 'Read the repository instructions and setup documentation. Explain the minimum setup and first useful verification task. Return missing requirements to the parent session. Report unavailable tools or credentials as prerequisites; do not claim unexecuted setup succeeded.', ['Setup prerequisites and source references', 'First verification task and observed blockers']],
+    ['release-prep', 'Release prep', 'Inspect the current release rules, version metadata and applicable verification evidence. Produce a release checklist and candidate notes tied to the source revision. Treat missing build, package, signing or publication proof as incomplete. Do not tag or publish merely because this runbook was installed.', ['Revision-bound release checklist', 'Release notes and unresolved gate evidence']],
+];
+/** Bundled data is compiled with core; scripts use only the existing workflow language. */
+export const bundledRunbooks = jobs.map(([id, name, instructions, expectedEvidence]) => ({
+    schemaVersion: 1, id, name, description: instructions.split('.')[0] + '.', instructions,
+    minimumNodeMajor: 20,
+    inputs: [{ name: 'goal', description: 'Requested scope, target, incident or review context.', required: id === 'deploy' || id === 'incident-triage' }],
+    requiredTools: [readers, ...(id === 'repo-orientation' || id === 'onboarding' ? [] : [commands])],
+    expectedEvidence: [...expectedEvidence], entrypoint: 'main.js', scripts: {
+        'main.js': `export const meta = ${JSON.stringify({ name: id, description: name, phases: ['inspect', 'report'] })};
+phase("inspect");
+const result = await agent(args.runbookInstructions + "\\n\\nUser scope: " + (args.goal ?? "Current repository"), { label: ${JSON.stringify(id)}, toolset: "research", failFast: true });
+phase("report");
+return { summary: result, expectedEvidence: args.runbookExpectedEvidence };
+`,
+    },
+}));

package/dist/runbooks/library.d.ts

@@ -0,0 +1,11 @@
+import { type ResolvedRunbook } from './package.js';
+export declare function findRunbook(source: string, cwd: string): Promise<ResolvedRunbook>;
+export declare function listRunbooks(cwd: string): Promise<{
+    runbooks: ResolvedRunbook[];
+    errors: string[];
+}>;
+/** Stage package data in the current project. Never executes scripts or changes permissions. */
+export declare function installRunbook(source: string, cwd: string): Promise<{
+    path: string;
+    book: ResolvedRunbook;
+}>;

package/dist/runbooks/library.js

@@ -0,0 +1,95 @@
+import { lstat, mkdir, readdir, realpath, rmdir } from 'node:fs/promises';
+import { join, resolve, relative } from 'node:path';
+import { writeFileAtomic } from '../utils/atomic_write.js';
+import { bundledRunbooks } from './catalog.js';
+import { RUNBOOK_MAX_BYTES, readRunbookPackage, resolveRunbookPackage } from './package.js';
+const safeId = /^[a-z][a-z0-9-]{0,63}$/u;
+const code = (error) => error.code;
+export async function findRunbook(source, cwd) {
+    if (safeId.test(source)) {
+        const installed = join(resolve(cwd), '.ztc', 'runbooks', source, 'runbook.json');
+        try {
+            const book = await readRunbookPackage(installed);
+            if (book.package.id !== source)
+                throw new Error('Package id does not match its installation directory');
+            return book;
+        }
+        catch (error) {
+            if (code(error) !== 'ENOENT')
+                throw error;
+        }
+        const bundled = bundledRunbooks.find(book => book.id === source);
+        if (bundled)
+            return resolveRunbookPackage(bundled, `bundled:${source}`);
+        throw new Error(`Runbook not found: ${source}. Use /runbooks list or provide a local runbook JSON path.`);
+    }
+    return readRunbookPackage(resolve(cwd, source));
+}
+export async function listRunbooks(cwd) {
+    const runbooks = new Map(bundledRunbooks.map(book => [book.id, resolveRunbookPackage(book, `bundled:${book.id}`)]));
+    const errors = [];
+    const root = join(resolve(cwd), '.ztc', 'runbooks');
+    let directories;
+    try {
+        directories = await readdir(root, { withFileTypes: true });
+    }
+    catch (error) {
+        if (code(error) !== 'ENOENT')
+            errors.push(`Cannot read runbook library ${root}: ${String(error).slice(0, 500)}`);
+        return { runbooks: [...runbooks.values()], errors };
+    }
+    const candidates = directories.filter(entry => entry.isDirectory() && safeId.test(entry.name)).sort((a, b) => a.name.localeCompare(b.name));
+    if (candidates.length > 128)
+        errors.push('Runbook library exceeds 128 packages; only the first 128 are displayed.');
+    for (const entry of candidates.slice(0, 128)) {
+        try {
+            const book = await readRunbookPackage(join(root, entry.name, 'runbook.json'));
+            if (book.package.id !== entry.name)
+                throw new Error('Package id does not match its installation directory');
+            runbooks.set(book.package.id, book);
+        }
+        catch (error) {
+            errors.push(`${entry.name}: ${String(error).slice(0, 500)}`);
+        }
+    }
+    return { runbooks: [...runbooks.values()].sort((a, b) => a.package.id.localeCompare(b.package.id)), errors };
+}
+/** Stage package data in the current project. Never executes scripts or changes permissions. */
+export async function installRunbook(source, cwd) {
+    const book = await findRunbook(source, cwd);
+    const manifest = JSON.stringify({ ...book.package, installedFrom: { source: book.source, digest: book.digest } }, null, 2) + '\n';
+    if (Buffer.byteLength(manifest) > RUNBOOK_MAX_BYTES)
+        throw new Error('Runbook installed package with retained origin exceeds 256 KiB; reduce its content before installation.');
+    const project = await realpath(cwd);
+    let root = project;
+    for (const component of ['.ztc', 'runbooks']) {
+        root = join(root, component);
+        await mkdir(root, { recursive: true });
+        const stat = await lstat(root);
+        if (stat.isSymbolicLink() || !stat.isDirectory() || relative(project, await realpath(root)).startsWith('..')) {
+            throw new Error(`Runbook installation requires a project-owned directory: ${root}`);
+        }
+    }
+    const destination = join(root, book.package.id);
+    try {
+        await mkdir(destination);
+    }
+    catch (error) {
+        if (code(error) === 'EEXIST')
+            throw new Error(`Runbook ${book.package.id} is already installed at ${destination}. Inspect the existing package; installation never overwrites it.`);
+        throw error;
+    }
+    const path = join(destination, 'runbook.json');
+    try {
+        await writeFileAtomic(path, manifest);
+    }
+    catch (error) {
+        // Remove only our empty reservation; never delete an existing package or another writer's files.
+        try {
+            await rmdir(destination);
+        }
+        catch { /* Incomplete files remain available for manual inspection. */ }
+        throw new Error(`Runbook installation incomplete at ${destination}: ${String(error).slice(0, 500)}`);
+    }
+    return { path, book };
+}

package/dist/runbooks/package.d.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+export declare const RUNBOOK_MAX_BYTES: number;
+declare const packageSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodString;
+    instructions: z.ZodString;
+    minimumNodeMajor: z.ZodNumber;
+    inputs: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+        required: z.ZodBoolean;
+    }, z.core.$strict>>;
+    requiredTools: z.ZodArray<z.ZodArray<z.ZodString>>;
+    expectedEvidence: z.ZodArray<z.ZodString>;
+    entrypoint: z.ZodString;
+    scripts: z.ZodRecord<z.ZodString, z.ZodString>;
+    installedFrom: z.ZodOptional<z.ZodObject<{
+        source: z.ZodString;
+        digest: z.ZodString;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type RunbookPackage = z.infer<typeof packageSchema>;
+export interface ResolvedRunbook {
+    package: RunbookPackage;
+    source: string;
+    digest: string;
+    installedFrom?: {
+        source: string;
+        digest: string;
+    };
+}
+/** Validate package data and the existing workflow language without executing scripts. */
+export declare function parseRunbookPackage(value: unknown): RunbookPackage;
+export declare function resolveRunbookPackage(value: unknown, source: string): ResolvedRunbook;
+export declare function readRunbookPackage(path: string): Promise<ResolvedRunbook>;
+/** Current host capabilities are prerequisites, not permission grants or evidence of execution. */
+export declare function prepareRunbookRun(book: ResolvedRunbook, inputs: unknown, tools: readonly string[], nodeVersion?: string): {
+    script: string;
+    args: Record<string, unknown>;
+};
+export {};

package/dist/runbooks/package.js

@@ -0,0 +1,102 @@
+import { createHash } from 'node:crypto';
+import { open } from 'node:fs/promises';
+import { z } from 'zod';
+import { parseWorkflowScript } from '../workflows/parser.js';
+export const RUNBOOK_MAX_BYTES = 256 * 1024;
+const id = z.string().regex(/^[a-z][a-z0-9-]{0,63}$/u);
+const scriptName = z.string().regex(/^[a-z][a-z0-9_-]{0,63}\.js$/u);
+const inputName = z.string().regex(/^[a-z][a-z0-9_]{0,63}$/u)
+    .refine(name => !name.startsWith('runbook') && !['constructor', 'prototype'].includes(name), 'Reserved input name');
+const text = z.string().min(1).max(4000);
+const packageSchema = z.object({
+    schemaVersion: z.literal(1),
+    id,
+    name: text,
+    description: text,
+    instructions: z.string().min(1).max(32 * 1024),
+    minimumNodeMajor: z.number().int().min(20).max(99),
+    inputs: z.array(z.object({ name: inputName, description: text, required: z.boolean() }).strict()).max(16),
+    requiredTools: z.array(z.array(z.string().regex(/^[A-Za-z][A-Za-z0-9_]{0,99}$/u)).min(1).max(8)).max(16),
+    expectedEvidence: z.array(text).min(1).max(16),
+    entrypoint: scriptName,
+    scripts: z.record(scriptName, z.string().min(1).max(128 * 1024))
+        .refine(scripts => Object.keys(scripts).length >= 1 && Object.keys(scripts).length <= 16, 'Use 1–16 workflow scripts'),
+    installedFrom: z.object({ source: text, digest: z.string().regex(/^[a-f0-9]{64}$/u) }).strict().optional(),
+}).strict();
+/** Validate package data and the existing workflow language without executing scripts. */
+export function parseRunbookPackage(value) {
+    const result = packageSchema.safeParse(value);
+    if (!result.success)
+        throw new Error(`Invalid runbook package (supported schemaVersion: 1): ${result.error.issues.map(issue => `${issue.path.join('.')}: ${issue.message}`).join('; ').slice(0, 1500)}`);
+    const book = result.data;
+    if (new Set(book.inputs.map(input => input.name)).size !== book.inputs.length)
+        throw new Error('Runbook input names must be unique');
+    if (!Object.hasOwn(book.scripts, book.entrypoint))
+        throw new Error(`Missing runbook entrypoint: ${book.entrypoint}`);
+    if (Buffer.byteLength(JSON.stringify(book)) > RUNBOOK_MAX_BYTES)
+        throw new Error('Runbook package exceeds 256 KiB');
+    for (const [name, script] of Object.entries(book.scripts)) {
+        try {
+            parseWorkflowScript(script);
+        }
+        catch (error) {
+            throw new Error(`Invalid runbook workflow ${name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    return book;
+}
+export function resolveRunbookPackage(value, source) {
+    const book = parseRunbookPackage(value);
+    const { installedFrom, ...content } = book;
+    return { package: book, source, digest: createHash('sha256').update(JSON.stringify(content)).digest('hex'),
+        ...(installedFrom ? { installedFrom } : {}) };
+}
+export async function readRunbookPackage(path) {
+    const file = await open(path, 'r');
+    try {
+        if (!(await file.stat()).isFile())
+            throw new Error('Runbook package must be a regular JSON file');
+        const buffer = Buffer.alloc(RUNBOOK_MAX_BYTES + 1);
+        let size = 0;
+        while (size < buffer.length) {
+            const read = await file.read(buffer, size, buffer.length - size, size);
+            if (!read.bytesRead)
+                break;
+            size += read.bytesRead;
+        }
+        if (size > RUNBOOK_MAX_BYTES)
+            throw new Error('Runbook package exceeds 256 KiB');
+        let value;
+        try {
+            value = JSON.parse(buffer.subarray(0, size).toString('utf8'));
+        }
+        catch {
+            throw new Error(`Runbook is not valid JSON: ${path}`);
+        }
+        return resolveRunbookPackage(value, path);
+    }
+    finally {
+        await file.close();
+    }
+}
+/** Current host capabilities are prerequisites, not permission grants or evidence of execution. */
+export function prepareRunbookRun(book, inputs, tools, nodeVersion = process.versions.node) {
+    const major = nodeVersion.match(/^(\d+)\.\d+\.\d+(?:[-+].*)?$/u)?.[1];
+    if (!major || Number(major) < book.package.minimumNodeMajor)
+        throw new Error(`Runbook ${book.package.id} requires Node ${book.package.minimumNodeMajor}+; current runtime is ${nodeVersion}. Update the ZTC runtime.`);
+    const missing = book.package.requiredTools.filter(alternatives => !alternatives.some(tool => tools.includes(tool)));
+    if (missing.length)
+        throw new Error(`Runbook ${book.package.id} needs registered tools: ${missing.map(names => names.join(' or ')).join(', ')}. Change to a compatible session/provider/mode; permission decisions still apply.`);
+    const fields = Object.fromEntries(book.package.inputs.map(input => {
+        const field = z.string().min(1).max(10_000);
+        return [input.name, input.required ? field : field.optional()];
+    }));
+    const result = z.object(fields).strict().safeParse(inputs);
+    if (!result.success)
+        throw new Error(`Invalid runbook inputs: ${result.error.issues.map(issue => `${issue.path.join('.') || 'inputs'}: ${issue.message}`).join('; ').slice(0, 1500)}. Use /runbooks show ${book.package.id} for input requirements.`);
+    return { script: book.package.scripts[book.package.entrypoint], args: {
+            ...result.data,
+            runbookInstructions: book.package.instructions, runbookSource: book.source,
+            runbookDigest: book.digest, runbookExpectedEvidence: book.package.expectedEvidence,
+        } };
+}