@webpresso/agent-kit 0.21.0

package/dist/esm/mcp/_tail-hints.js

@@ -0,0 +1,86 @@
+/**
+ * Tail-hint rate limiting for blueprint MCP tools.
+ *
+ * Hints are static strings shown at the end of tool responses to nudge the
+ * agent toward the next logical step. Rate-limited per hint per cwd — once
+ * shown, a hint is suppressed for 7 days so it doesn't flood every response.
+ *
+ * History is persisted to `.agent/.tail-hint-history.jsonl` in the consumer
+ * repo. Each line is a JSON record: `{ hintId, cwd, ts }`.
+ */
+import { appendFileSync, existsSync, readFileSync, mkdirSync } from 'node:fs';
+import path from 'node:path';
+import { getSurfacePath, NotInGitRepoError } from '#paths/state-root.js';
+export const TAIL_HINTS = {
+    PLL_PARALLEL: 'Consider /pll for parallel execution.',
+    VERIFY_DONE: 'Run /verify to confirm done-ness before finalizing.',
+    PLAN_REFINE: 'Run /plan-refine to harden this blueprint.',
+    AUDIT_FIX: 'Run /verify or `wp audit --fix` before finalizing.',
+};
+const HINT_HISTORY_FILENAME = '.tail-hint-history.jsonl';
+const SEVEN_DAYS_MS = 7 * 24 * 60 * 60 * 1000;
+function historyPath(cwd) {
+    try {
+        return getSurfacePath('hints/tail-history.jsonl', 'repo', cwd);
+    }
+    catch (err) {
+        if (err instanceof NotInGitRepoError)
+            return path.join(cwd, '.agent', HINT_HISTORY_FILENAME);
+        throw err;
+    }
+}
+function readHistory(cwd) {
+    const file = historyPath(cwd);
+    if (!existsSync(file))
+        return [];
+    const lines = readFileSync(file, 'utf8')
+        .split('\n')
+        .filter((l) => l.trim().length > 0);
+    const records = [];
+    for (const line of lines) {
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed !== null &&
+                typeof parsed === 'object' &&
+                'hintId' in parsed &&
+                'cwd' in parsed &&
+                'ts' in parsed) {
+                records.push(parsed);
+            }
+        }
+        catch {
+            // skip malformed lines
+        }
+    }
+    return records;
+}
+/**
+ * Returns true when the hint should be shown (not shown in last 7 days).
+ */
+export function shouldShowHint(cwd, hintId) {
+    const history = readHistory(cwd);
+    const cutoff = Date.now() - SEVEN_DAYS_MS;
+    const recent = history.find((r) => r.hintId === hintId && r.cwd === cwd && r.ts >= cutoff);
+    return recent === undefined;
+}
+/**
+ * Records that the hint was shown. Appends to `.agent/.tail-hint-history.jsonl`.
+ */
+export function recordHint(cwd, hintId) {
+    const file = historyPath(cwd);
+    const dir = path.dirname(file);
+    mkdirSync(dir, { recursive: true });
+    const record = { hintId, cwd, ts: Date.now() };
+    appendFileSync(file, JSON.stringify(record) + '\n', 'utf8');
+}
+/**
+ * Returns the hint string if it should be shown, otherwise null.
+ * Also records the hint if shown.
+ */
+export function maybeHint(cwd, hintId) {
+    if (!shouldShowHint(cwd, hintId))
+        return null;
+    recordHint(cwd, hintId);
+    return TAIL_HINTS[hintId];
+}
+//# sourceMappingURL=_tail-hints.js.map

package/dist/esm/mcp/auto-discover.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Tool auto-discovery for the `wp mcp` server.
+ *
+ * Scans a directory for `*.ts` (source) or `*.js` (built) files, dynamic-imports
+ * each, and registers any default-exported {@link ToolDescriptor} on the
+ * provided server. Skips test files (`*.test.*`, `*.integration.test.*`) and
+ * type-declaration files.
+ *
+ * Adding a new tool is a one-file affair: drop `src/mcp/tools/<name>.ts` with a
+ * default export and the server picks it up at startup. No edits to
+ * `server.ts` required.
+ */
+import { type ZodType } from 'zod';
+export interface ContentBlock {
+    readonly type: string;
+    readonly text?: string;
+    readonly [key: string]: unknown;
+}
+export interface ToolHandlerResult {
+    readonly content: readonly ContentBlock[];
+    readonly structuredContent?: Record<string, unknown>;
+    readonly isError?: boolean;
+}
+/**
+ * MCP tool annotations (spec 2025-03-26). Servers MUST opt into read-only /
+ * idempotent / closed-world; clients otherwise pessimize and gate every call
+ * behind a confirmation prompt. Set explicitly per tool — defaults are
+ * intentionally pessimistic.
+ */
+export interface ToolAnnotations {
+    readonly title?: string;
+    readonly readOnlyHint?: boolean;
+    readonly destructiveHint?: boolean;
+    readonly idempotentHint?: boolean;
+    readonly openWorldHint?: boolean;
+}
+export interface ToolHandlerExtra {
+    readonly signal?: AbortSignal;
+}
+export type ToolHandler = (input: unknown, extra?: ToolHandlerExtra) => Promise<ToolHandlerResult>;
+export interface ToolDescriptor {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: ZodType<unknown> | {
+        _def: unknown;
+        parse: (x: unknown) => unknown;
+    };
+    readonly outputSchema?: ZodType<unknown> | {
+        _def: unknown;
+        parse: (x: unknown) => unknown;
+    };
+    readonly handler: ToolHandler;
+    readonly annotations?: ToolAnnotations;
+}
+/**
+ * Minimal server contract used by the auto-discovery loop. The real MCP
+ * `Server` instance and `McpServer` instance both implement a richer surface,
+ * but discovery only needs `registerTool`. Keeping the shape minimal makes the
+ * function trivially fakeable in tests.
+ */
+export interface ToolRegistrar {
+    registerTool(name: string, description: string, jsonSchema: Record<string, unknown>, outputSchema: Record<string, unknown> | undefined, handler: ToolHandler, annotations?: ToolAnnotations): void;
+}
+export declare function discoverTools(server: ToolRegistrar, toolsDir: string): Promise<ToolDescriptor[]>;
+//# sourceMappingURL=auto-discover.d.ts.map

package/dist/esm/mcp/auto-discover.js

@@ -0,0 +1,108 @@
+/**
+ * Tool auto-discovery for the `wp mcp` server.
+ *
+ * Scans a directory for `*.ts` (source) or `*.js` (built) files, dynamic-imports
+ * each, and registers any default-exported {@link ToolDescriptor} on the
+ * provided server. Skips test files (`*.test.*`, `*.integration.test.*`) and
+ * type-declaration files.
+ *
+ * Adding a new tool is a one-file affair: drop `src/mcp/tools/<name>.ts` with a
+ * default export and the server picks it up at startup. No edits to
+ * `server.ts` required.
+ */
+import { readdir } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+const SKIP_SUFFIXES = ['.test.ts', '.test.js', '.integration.test.ts', '.integration.test.js'];
+const SUPPORTED_EXTENSIONS = new Set(['.ts', '.js', '.mjs', '.cjs']);
+function shouldSkip(file) {
+    if (file.endsWith('.d.ts') || file.endsWith('.d.ts.map'))
+        return true;
+    if (file.endsWith('.js.map') || file.endsWith('.ts.map'))
+        return true;
+    for (const suffix of SKIP_SUFFIXES) {
+        if (file.endsWith(suffix))
+            return true;
+    }
+    const ext = extname(file);
+    if (!SUPPORTED_EXTENSIONS.has(ext))
+        return true;
+    return false;
+}
+function isPlainObjectSchema(value) {
+    return Boolean(value) && typeof value === 'object' && Object.keys(value).length > 1;
+}
+/**
+ * Convert a tool's zod input schema to a JSON Schema for MCP. Prefers zod v4's
+ * native `toJSONSchema` (the package pins ^4.3.6); falls through to the
+ * `zod-to-json-schema` v3 adapter; and finally throws — silent fallback to a
+ * permissive `{type:'object'}` would mask schema bugs by accepting any input.
+ *
+ * The lone permitted fallback is for *bare-shape* descriptors used by tests
+ * (`{ _def, parse }` ducks that aren't zod instances). Those cannot be
+ * auto-converted; we still mark them explicitly via `bareShape: true` rather
+ * than silently producing an empty schema, so the MCP client sees the
+ * limitation.
+ */
+// Real zod v4 schemas carry an internal `_zod` marker. The bare-shape ducks
+// used by `auto-discover.test.ts` (`{ _def, parse }`) do not — discriminate
+// on that to keep philosophy gates intact: bare shapes get an explicit
+// `bareShape: true` JSON Schema (no silent fallback), and neither input
+// reaches an exception-swallowing try/catch.
+function isZodV4Instance(schema) {
+    return Boolean(schema) && typeof schema === 'object' && '_zod' in schema;
+}
+function isBareShapeDuck(schema) {
+    return (Boolean(schema) &&
+        typeof schema === 'object' &&
+        '_def' in schema &&
+        'parse' in schema);
+}
+function toJsonSchema(schema) {
+    if (isZodV4Instance(schema)) {
+        const ztoj = z
+            .toJSONSchema;
+        if (typeof ztoj === 'function') {
+            const result = ztoj(schema);
+            if (isPlainObjectSchema(result))
+                return result;
+        }
+        const v3Result = zodToJsonSchema(schema);
+        if (isPlainObjectSchema(v3Result))
+            return v3Result;
+        throw new Error('Cannot derive JSON Schema from zod schema — ' +
+            'neither zod v4 toJSONSchema nor zod-to-json-schema produced a usable result');
+    }
+    if (isBareShapeDuck(schema)) {
+        return { type: 'object', bareShape: true };
+    }
+    throw new Error('Tool input schema is neither a zod schema nor a recognised bare shape');
+}
+export async function discoverTools(server, toolsDir) {
+    const entries = await readdir(toolsDir, { withFileTypes: true });
+    const registered = [];
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (shouldSkip(entry.name))
+            continue;
+        const fullPath = join(toolsDir, entry.name);
+        const moduleUrl = pathToFileURL(fullPath).href;
+        const mod = (await import(moduleUrl));
+        const descriptor = mod.default;
+        if (!descriptor || typeof descriptor !== 'object') {
+            throw new Error(`Tool file ${fullPath} has no default export`);
+        }
+        if (typeof descriptor.name !== 'string' || typeof descriptor.handler !== 'function') {
+            throw new Error(`Tool file ${fullPath} default export is malformed (missing name or handler)`);
+        }
+        const jsonSchema = toJsonSchema(descriptor.inputSchema);
+        const outputSchema = descriptor.outputSchema ? toJsonSchema(descriptor.outputSchema) : undefined;
+        server.registerTool(descriptor.name, descriptor.description, jsonSchema, outputSchema, descriptor.handler, descriptor.annotations);
+        registered.push(descriptor);
+    }
+    return registered;
+}
+//# sourceMappingURL=auto-discover.js.map

package/dist/esm/mcp/blueprint-server.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Blueprint structured-store MCP server — 8 tools for the blueprint DB.
+ *
+ * Call `registerBlueprintTools(registrar, cwd)` from server startup.
+ * It calls `coldStartIfNeeded` once then registers all 8 tools.
+ *
+ * All outputs honour the summary-first envelope: { summary, failures, bytes, tokensSaved }
+ *
+ * Platform-first sync (Task 2.1):
+ *   When a SyncAdapter is available (credentials present, not disabled), mutations
+ *   push a BlueprintPlatformEvent before updating local markdown/SQLite.
+ *   Iron rule: WP_BLUEPRINT_PLATFORM_DISABLED=1 skips the adapter entirely — the
+ *   markdown-canonical path runs byte-identically to the pre-migration behaviour.
+ */
+import { type ProjectResolver } from '#project-resolver.js';
+import type { ToolRegistrar } from './auto-discover.js';
+/**
+ * Minimal platform sync surface needed by blueprint-server handlers.
+ *
+ * The production factory creates a BlueprintSyncClient + ReplicaManager pair.
+ * Tests inject a mock via `_setSyncAdapterFactory`.
+ *
+ * Keeping this interface here (rather than importing BlueprintPlatformClient
+ * directly) avoids coupling blueprint-server to the client implementation and
+ * keeps the module testable without live credentials.
+ */
+export interface SyncAdapter {
+    pushEvent(event: {
+        readonly eventId: string;
+        readonly repoId: string;
+        readonly occurredAt: string;
+        readonly type: 'task.status_changed';
+        readonly payload: {
+            readonly type: 'task.status_changed';
+            readonly blueprintSlug: string;
+            readonly taskId: string;
+            readonly fromStatus: string;
+            readonly toStatus: string;
+        };
+    } | {
+        readonly eventId: string;
+        readonly repoId: string;
+        readonly occurredAt: string;
+        readonly type: 'blueprint.status_changed';
+        readonly payload: {
+            readonly type: 'blueprint.status_changed';
+            readonly slug: string;
+            readonly fromStatus: string;
+            readonly toStatus: string;
+        };
+    } | {
+        readonly eventId: string;
+        readonly repoId: string;
+        readonly occurredAt: string;
+        readonly type: 'blueprint.finalized';
+        readonly payload: {
+            readonly type: 'blueprint.finalized';
+            readonly slug: string;
+        };
+    } | {
+        readonly eventId: string;
+        readonly repoId: string;
+        readonly occurredAt: string;
+        readonly type: 'blueprint.created';
+        readonly payload: {
+            readonly type: 'blueprint.created';
+            readonly slug: string;
+            readonly title: string;
+            readonly complexity: string;
+            readonly status: string;
+        };
+    }): Promise<void>;
+    ensureFresh(opts?: {
+        readonly slug?: string;
+    }): Promise<void>;
+}
+type SyncAdapterFactory = () => SyncAdapter | null;
+/**
+ * Override the adapter factory — for tests only.
+ * Pass `null` to restore the production default.
+ *
+ * @internal
+ */
+export declare function _setSyncAdapterFactory(factory: SyncAdapterFactory | null): void;
+export declare function registerBlueprintTools(registrar: ToolRegistrar, cwd: string, projectResolver?: ProjectResolver): Promise<void>;
+/**
+ * Options for {@link registerBlueprintServer}.
+ *
+ * @property cwd                Repo working directory (defaults to process.cwd()).
+ * @property existingToolNames  Names of tools already registered by the
+ *                              auto-discover step. Registration HARD-FAILS on
+ *                              collision (F13/E15) — silent shadowing would
+ *                              hide name drift from CI.
+ * @property getMcpRoots        Lazy callback that returns the current MCP
+ *                              client roots. Catch unsupported-capability
+ *                              errors *inside* this callback or let them
+ *                              throw — `wp_blueprint_projects` degrades
+ *                              gracefully to current-cwd + warning.
+ * @property onRootsListChanged Optional callback to install a notification
+ *                              handler for `RootsListChangedNotificationSchema`.
+ *                              When the client emits the notification, invoke
+ *                              the callback (no args) and the roots cache will
+ *                              be invalidated. Callers wire this via
+ *                              `server.setNotificationHandler(...)` (F5).
+ */
+export interface RegisterBlueprintServerOptions {
+    readonly cwd?: string;
+    readonly existingToolNames: ReadonlySet<string>;
+    readonly projectResolver?: ProjectResolver;
+    readonly getMcpRoots?: () => Promise<{
+        readonly roots: ReadonlyArray<{
+            readonly uri: string;
+            readonly name?: string;
+        }>;
+    }>;
+    readonly onRootsListChanged?: (handler: () => void) => void;
+}
+/**
+ * Wire the blueprint structured-store tools into the main MCP server.
+ *
+ * Single integration point (F13/E15): call this once from `createServer` AFTER
+ * `auto-discover` finishes so tool-name collisions surface as a registration
+ * error rather than silent shadow. Adds `wp_blueprint_projects` on top of the
+ * 8 existing tools.
+ *
+ * Roots handling (F5):
+ * - Roots are looked up lazily via `getMcpRoots` (callers pass a thunk that
+ *   calls `server.listRoots()`). If the client does not support roots, the
+ *   callback throws `assertClientCapability` — that throw is caught here, the
+ *   tool result includes an `unsupported_roots` warning, and the current
+ *   project still resolves from cwd.
+ * - `onRootsListChanged` lets the caller hook a notification handler so the
+ *   cached roots invalidate on the next read.
+ */
+export declare function registerBlueprintServer(registrar: ToolRegistrar, options: RegisterBlueprintServerOptions): Promise<void>;
+export {};
+//# sourceMappingURL=blueprint-server.d.ts.map