dcp-wrap 0.2.0

package/dist/picoclaw-hook.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * PicoClaw DCP Hook — out-of-process JSON-RPC over stdio.
+ *
+ * Two-hook pattern:
+ *   before_tool — injects queryType=agent for MCP tools with DCP output mode
+ *   after_tool  — DCP-encodes JSON tool results (fallback for tools without native DCP)
+ *
+ * Config via PICOCLAW_DCP_TOOLS env (JSON):
+ *   {
+ *     "mcp_engram_engram_pull": { "id": "engram-recall:v1", "fields": [...] },
+ *     "web_fetch": "auto"
+ *   }
+ *
+ * Config via PICOCLAW_DCP_AGENT_TOOLS env (comma-separated):
+ *   Tools where before_tool injects queryType=agent.
+ *   Example: "mcp_engram_engram_pull,mcp_engram_engram_ls"
+ */
+import { createInterface } from "node:readline";
+import { dcpEncode, SchemaGenerator } from "./index.js";
+// --- State ---
+let toolsConfig = {};
+let agentQueryTools = new Set();
+const autoSchemaCache = new Map();
+// --- Config loading ---
+function loadConfig() {
+    const envTools = process.env.PICOCLAW_DCP_TOOLS;
+    if (envTools) {
+        try {
+            toolsConfig = JSON.parse(envTools);
+        }
+        catch {
+            log(`Failed to parse PICOCLAW_DCP_TOOLS`);
+        }
+    }
+    const envAgent = process.env.PICOCLAW_DCP_AGENT_TOOLS;
+    if (envAgent) {
+        agentQueryTools = new Set(envAgent.split(",").map((s) => s.trim()).filter(Boolean));
+    }
+}
+// --- Logging ---
+function log(msg) {
+    process.stderr.write(`[dcp-hook] ${msg}\n`);
+}
+// --- JSON-RPC ---
+function sendResponse(id, result) {
+    const msg = { jsonrpc: "2.0", id, result };
+    process.stdout.write(JSON.stringify(msg) + "\n");
+}
+function sendError(id, code, message) {
+    const msg = { jsonrpc: "2.0", id, error: { code, message } };
+    process.stdout.write(JSON.stringify(msg) + "\n");
+}
+// --- DCP encoding ---
+function tryParseJSON(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (Array.isArray(parsed)) {
+            if (parsed.length > 0 && typeof parsed[0] === "object" && parsed[0] !== null) {
+                return parsed;
+            }
+            return null;
+        }
+        if (typeof parsed === "object" && parsed !== null) {
+            return [parsed];
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function encodeToolResult(toolName, forLlm) {
+    const config = toolsConfig[toolName];
+    if (!config)
+        return null;
+    const records = tryParseJSON(forLlm);
+    if (!records)
+        return null;
+    if (config === "auto") {
+        return encodeAuto(toolName, records);
+    }
+    const schema = { id: config.id, fields: config.fields };
+    return dcpEncode(records, schema);
+}
+function encodeAuto(toolName, records) {
+    let schema = autoSchemaCache.get(toolName);
+    if (!schema) {
+        const gen = new SchemaGenerator();
+        const draft = gen.fromSamples(records, {
+            domain: toolName,
+            maxDepth: 3,
+            maxFields: 20,
+        });
+        schema = { id: draft.schema.id, fields: draft.schema.fields };
+        autoSchemaCache.set(toolName, schema);
+        log(`auto-schema ${toolName}: ${schema.fields.join(",")}`);
+    }
+    return dcpEncode(records, schema);
+}
+// --- Hook handlers ---
+function handleHello(_params) {
+    return { ok: true, name: "dcp-encoder" };
+}
+function handleBeforeTool(params) {
+    const payload = params;
+    if (agentQueryTools.has(payload.tool)) {
+        return {
+            action: "modify",
+            call: {
+                ...payload,
+                arguments: { ...payload.arguments, queryType: "agent" },
+            },
+        };
+    }
+    return { action: "continue" };
+}
+function handleAfterTool(params) {
+    const payload = params;
+    const toolName = payload.tool;
+    const result = payload.result;
+    if (!result || result.is_error || !result.for_llm) {
+        return { action: "continue" };
+    }
+    const encoded = encodeToolResult(toolName, result.for_llm);
+    if (!encoded) {
+        return { action: "continue" };
+    }
+    const originalLen = result.for_llm.length;
+    const encodedLen = encoded.length;
+    const pct = ((1 - encodedLen / originalLen) * 100).toFixed(0);
+    log(`${toolName}: ${originalLen}→${encodedLen} (${pct}%)`);
+    return {
+        action: "modify",
+        result: {
+            ...payload,
+            result: { ...result, for_llm: encoded },
+        },
+    };
+}
+function handleRequest(method, params) {
+    switch (method) {
+        case "hook.hello":
+            return handleHello((params ?? {}));
+        case "hook.before_tool":
+            return handleBeforeTool(params);
+        case "hook.after_tool":
+            return handleAfterTool(params);
+        case "hook.before_llm":
+        case "hook.after_llm":
+        case "hook.approve_tool":
+            return { action: "continue" };
+        default:
+            throw new Error(`method not found: ${method}`);
+    }
+}
+// --- Main loop ---
+function main() {
+    loadConfig();
+    const dcpTools = Object.keys(toolsConfig);
+    const agentTools = [...agentQueryTools];
+    log(`dcp=${dcpTools.join(",") || "none"} agent=${agentTools.join(",") || "none"}`);
+    const rl = createInterface({ input: process.stdin });
+    rl.on("line", (line) => {
+        if (!line.trim())
+            return;
+        let msg;
+        try {
+            msg = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (!msg.id)
+            return;
+        try {
+            const result = handleRequest(msg.method ?? "", msg.params);
+            sendResponse(msg.id, result);
+        }
+        catch (err) {
+            sendError(msg.id, -32000, err.message);
+        }
+    });
+    rl.on("close", () => {
+        process.exit(0);
+    });
+}
+main();
+//# sourceMappingURL=picoclaw-hook.js.map

package/dist/picoclaw-hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"picoclaw-hook.js","sourceRoot":"","sources":["../src/picoclaw-hook.ts"],"names":[],"mappings":"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"}

package/dist/picoclaw-hook.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/picoclaw-hook.test.js

@@ -0,0 +1,200 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const hookPath = resolve(__dirname, "../dist/picoclaw-hook.js");
+function startHook(cfg) {
+    const env = { ...process.env };
+    if (cfg?.tools) {
+        env.PICOCLAW_DCP_TOOLS = JSON.stringify(cfg.tools);
+    }
+    if (cfg?.agentTools) {
+        env.PICOCLAW_DCP_AGENT_TOOLS = cfg.agentTools.join(",");
+    }
+    return spawn("node", [hookPath], {
+        stdio: ["pipe", "pipe", "pipe"],
+        env,
+    });
+}
+function rpc(proc, id, method, params) {
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => reject(new Error(`timeout for ${method}`)), 5000);
+        const onData = (chunk) => {
+            const lines = chunk.toString().split("\n").filter(Boolean);
+            for (const line of lines) {
+                try {
+                    const msg = JSON.parse(line);
+                    if (msg.id === id) {
+                        clearTimeout(timeout);
+                        proc.stdout.off("data", onData);
+                        if (msg.error)
+                            reject(new Error(msg.error.message));
+                        else
+                            resolve(msg.result);
+                    }
+                }
+                catch { /* ignore parse errors */ }
+            }
+        };
+        proc.stdout.on("data", onData);
+        proc.stdin.write(JSON.stringify({ jsonrpc: "2.0", id, method, params }) + "\n");
+    });
+}
+describe("picoclaw-hook", () => {
+    it("responds to hook.hello", async () => {
+        const proc = startHook();
+        try {
+            const result = await rpc(proc, 1, "hook.hello", { name: "test", version: 1, modes: ["tool"] });
+            assert.deepStrictEqual(result, { ok: true, name: "dcp-encoder" });
+        }
+        finally {
+            proc.kill();
+        }
+    });
+    it("passes through unconfigured tools", async () => {
+        const proc = startHook({ tools: {} });
+        try {
+            await rpc(proc, 1, "hook.hello", {});
+            const result = await rpc(proc, 2, "hook.after_tool", {
+                meta: { session_key: "s1" },
+                tool: "unknown_tool",
+                result: { for_llm: '{"foo":"bar"}', silent: false, is_error: false },
+            });
+            assert.deepStrictEqual(result, { action: "continue" });
+        }
+        finally {
+            proc.kill();
+        }
+    });
+    it("DCP-encodes configured tool results", async () => {
+        const proc = startHook({
+            tools: {
+                mcp_engram_pull: {
+                    id: "engram-recall:v1",
+                    fields: ["id", "relevance", "summary", "tags"],
+                },
+            },
+        });
+        try {
+            await rpc(proc, 1, "hook.hello", {});
+            const toolOutput = JSON.stringify([
+                { id: "abc-123", relevance: 0.95, summary: "Test node", tags: ["howto", "gateway"], hitCount: 3, weight: 1.2 },
+                { id: "def-456", relevance: 0.72, summary: "Another node", tags: ["why"], hitCount: 1, weight: 0.5 },
+            ]);
+            const result = (await rpc(proc, 2, "hook.after_tool", {
+                meta: { session_key: "s1" },
+                tool: "mcp_engram_pull",
+                result: { for_llm: toolOutput, silent: false, is_error: false },
+            }));
+            assert.equal(result.action, "modify");
+            const encoded = result.result.result.for_llm;
+            assert.ok(encoded.includes("$S"));
+            assert.ok(encoded.includes("engram-recall:v1"));
+            assert.ok(encoded.length < toolOutput.length);
+            const lines = encoded.split("\n");
+            assert.equal(lines.length, 3, "header + 2 data rows");
+            const header = JSON.parse(lines[0]);
+            assert.equal(header[0], "$S");
+            assert.equal(header[1], "engram-recall:v1");
+        }
+        finally {
+            proc.kill();
+        }
+    });
+    it("passes through error results without encoding", async () => {
+        const proc = startHook({
+            tools: { mcp_engram_pull: { id: "test:v1", fields: ["id", "summary"] } },
+        });
+        try {
+            await rpc(proc, 1, "hook.hello", {});
+            const result = await rpc(proc, 2, "hook.after_tool", {
+                meta: {},
+                tool: "mcp_engram_pull",
+                result: { for_llm: "Error: connection refused", is_error: true },
+            });
+            assert.deepStrictEqual(result, { action: "continue" });
+        }
+        finally {
+            proc.kill();
+        }
+    });
+    it("passes through non-JSON tool output", async () => {
+        const proc = startHook({
+            tools: { mcp_engram_pull: { id: "test:v1", fields: ["id", "summary"] } },
+        });
+        try {
+            await rpc(proc, 1, "hook.hello", {});
+            const result = await rpc(proc, 2, "hook.after_tool", {
+                meta: {},
+                tool: "mcp_engram_pull",
+                result: { for_llm: "This is just plain text output", is_error: false },
+            });
+            assert.deepStrictEqual(result, { action: "continue" });
+        }
+        finally {
+            proc.kill();
+        }
+    });
+    it("auto-generates schema for 'auto' tools", async () => {
+        const proc = startHook({ tools: { web_search: "auto" } });
+        try {
+            await rpc(proc, 1, "hook.hello", {});
+            const toolOutput = JSON.stringify([
+                { title: "Result 1", url: "https://example.com/1", snippet: "First result snippet", score: 0.9 },
+                { title: "Result 2", url: "https://example.com/2", snippet: "Second result snippet", score: 0.7 },
+            ]);
+            const result = (await rpc(proc, 2, "hook.after_tool", {
+                meta: {},
+                tool: "web_search",
+                result: { for_llm: toolOutput, is_error: false },
+            }));
+            assert.equal(result.action, "modify");
+            const encoded = result.result.result.for_llm;
+            assert.ok(encoded.includes("$S"));
+            assert.ok(encoded.length < toolOutput.length);
+        }
+        finally {
+            proc.kill();
+        }
+    });
+    it("before_tool injects queryType=agent for configured tools", async () => {
+        const proc = startHook({
+            agentTools: ["mcp_engram_engram_pull", "mcp_engram_engram_ls"],
+        });
+        try {
+            await rpc(proc, 1, "hook.hello", {});
+            const result = (await rpc(proc, 2, "hook.before_tool", {
+                meta: { session_key: "s1" },
+                tool: "mcp_engram_engram_pull",
+                arguments: { query: "DCP", limit: 10 },
+            }));
+            assert.equal(result.action, "modify");
+            assert.equal(result.call?.arguments?.queryType, "agent");
+            assert.equal(result.call?.arguments?.query, "DCP");
+            assert.equal(result.call?.arguments?.limit, 10);
+        }
+        finally {
+            proc.kill();
+        }
+    });
+    it("before_tool passes through non-agent tools", async () => {
+        const proc = startHook({
+            agentTools: ["mcp_engram_engram_pull"],
+        });
+        try {
+            await rpc(proc, 1, "hook.hello", {});
+            const result = await rpc(proc, 2, "hook.before_tool", {
+                meta: {},
+                tool: "web_search",
+                arguments: { query: "test" },
+            });
+            assert.deepStrictEqual(result, { action: "continue" });
+        }
+        finally {
+            proc.kill();
+        }
+    });
+});
+//# sourceMappingURL=picoclaw-hook.test.js.map

package/dist/picoclaw-hook.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"picoclaw-hook.test.js","sourceRoot":"","sources":["../src/picoclaw-hook.test.ts"],"names":[],"mappings":"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"}

package/dist/schema.d.ts

@@ -0,0 +1,29 @@
+import type { DcpSchemaDef, FieldTypeDef } from "./types.js";
+export declare class DcpSchema {
+    readonly id: string;
+    readonly description: string;
+    readonly fields: string[];
+    readonly fieldCount: number;
+    readonly types: Record<string, FieldTypeDef>;
+    constructor(def: DcpSchemaDef);
+    /** Bitmask with all field bits set. */
+    get fullMask(): number;
+    /** Return the bit value for a field (MSB = first field). */
+    fieldBit(fieldName: string): number;
+    /** Return field names corresponding to set bits in mask. */
+    fieldsFromMask(mask: number): string[];
+    /** Generate cutdown schema ID: base_id#hex_mask. */
+    cutdownId(mask: number): string;
+    /** Generate $S header array. */
+    sHeader(mask?: number): unknown[];
+    /** Validate a positional array against this schema. Returns error messages. */
+    validateRow(row: unknown[], mask?: number): string[];
+    /** Export as JSON-serializable definition. */
+    toDef(): DcpSchemaDef;
+    /** Save schema definition to a JSON file. */
+    save(path: string): void;
+    /** Load schema from a JSON file. */
+    static fromFile(path: string): DcpSchema;
+    /** Load schema from a parsed JSON object. */
+    static fromDef(data: Record<string, unknown>): DcpSchema;
+}

package/dist/schema.js

@@ -0,0 +1,120 @@
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+export class DcpSchema {
+    id;
+    description;
+    fields;
+    fieldCount;
+    types;
+    constructor(def) {
+        this.id = def.id;
+        this.description = def.description;
+        this.fields = [...def.fields];
+        this.fieldCount = def.fieldCount;
+        this.types = { ...def.types };
+    }
+    /** Bitmask with all field bits set. */
+    get fullMask() {
+        return (1 << this.fieldCount) - 1;
+    }
+    /** Return the bit value for a field (MSB = first field). */
+    fieldBit(fieldName) {
+        const idx = this.fields.indexOf(fieldName);
+        if (idx === -1)
+            throw new Error(`field not found: ${fieldName}`);
+        return 1 << (this.fieldCount - 1 - idx);
+    }
+    /** Return field names corresponding to set bits in mask. */
+    fieldsFromMask(mask) {
+        return this.fields.filter((_, i) => mask & (1 << (this.fieldCount - 1 - i)));
+    }
+    /** Generate cutdown schema ID: base_id#hex_mask. */
+    cutdownId(mask) {
+        if (mask === this.fullMask)
+            return this.id;
+        return `${this.id}#${mask.toString(16)}`;
+    }
+    /** Generate $S header array. */
+    sHeader(mask) {
+        const m = mask ?? this.fullMask;
+        const active = this.fieldsFromMask(m);
+        const sid = this.cutdownId(m);
+        return ["$S", sid, ...active];
+    }
+    /** Validate a positional array against this schema. Returns error messages. */
+    validateRow(row, mask) {
+        const active = mask != null ? this.fieldsFromMask(mask) : this.fields;
+        const errors = [];
+        if (row.length !== active.length) {
+            errors.push(`expected ${active.length} fields, got ${row.length}`);
+            return errors;
+        }
+        for (let i = 0; i < active.length; i++) {
+            const fname = active[i];
+            const ft = this.types[fname];
+            if (!ft)
+                continue;
+            const value = row[i];
+            const err = validateField(ft, value);
+            if (err)
+                errors.push(`field ${fname} (pos ${i}): ${err}`);
+        }
+        return errors;
+    }
+    /** Export as JSON-serializable definition. */
+    toDef() {
+        return {
+            $dcp: "schema",
+            id: this.id,
+            description: this.description,
+            fields: [...this.fields],
+            fieldCount: this.fieldCount,
+            types: { ...this.types },
+        };
+    }
+    /** Save schema definition to a JSON file. */
+    save(path) {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(this.toDef(), null, 2) + "\n", "utf-8");
+    }
+    /** Load schema from a JSON file. */
+    static fromFile(path) {
+        const data = JSON.parse(readFileSync(path, "utf-8"));
+        return DcpSchema.fromDef(data);
+    }
+    /** Load schema from a parsed JSON object. */
+    static fromDef(data) {
+        if (data.$dcp !== "schema") {
+            throw new Error("not a DCP schema: missing or invalid $dcp marker");
+        }
+        return new DcpSchema(data);
+    }
+}
+function validateField(ft, value) {
+    const types = Array.isArray(ft.type) ? ft.type : [ft.type];
+    if (value === null || value === undefined) {
+        return types.includes("null") ? null : "null not allowed";
+    }
+    let typeOk = false;
+    for (const t of types) {
+        if (t === "string" && typeof value === "string")
+            typeOk = true;
+        else if (t === "number" && typeof value === "number")
+            typeOk = true;
+        else if (t === "boolean" && typeof value === "boolean")
+            typeOk = true;
+    }
+    if (!typeOk)
+        return `expected ${ft.type}, got ${typeof value}`;
+    if (ft.enum != null && !ft.enum.includes(value)) {
+        return `value ${JSON.stringify(value)} not in enum`;
+    }
+    if (ft.min != null && typeof value === "number" && value < ft.min) {
+        return `value ${value} < min ${ft.min}`;
+    }
+    if (ft.max != null && typeof value === "number" && value > ft.max) {
+        return `value ${value} > max ${ft.max}`;
+    }
+    return null;
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,62 @@
+/** Type definition for a single schema field. */
+export interface FieldTypeDef {
+    type: string | string[];
+    description?: string;
+    enum?: unknown[];
+    min?: number;
+    max?: number;
+}
+/** DCP schema definition (the $dcp JSON document). */
+export interface DcpSchemaDef {
+    $dcp: "schema";
+    id: string;
+    description: string;
+    fields: string[];
+    fieldCount: number;
+    types: Record<string, FieldTypeDef>;
+}
+/** Mapping: schema field name → dot.notation.path in source. */
+export interface FieldMappingDef {
+    schemaId: string;
+    paths: Record<string, string>;
+}
+/** Options for schema generation. */
+export interface GenerateOptions {
+    domain: string;
+    version?: number;
+    description?: string;
+    include?: string[];
+    exclude?: string[];
+    fieldNames?: Record<string, string>;
+    /** Max nesting depth to flatten (default: 3). Deeper paths are ignored. */
+    maxDepth?: number;
+    /** Max fields in generated schema (default: 20). Lowest-presence fields are dropped. */
+    maxFields?: number;
+    /** Min presence rate to include a field, 0-1 (default: 0.1). Fields appearing in <10% of samples are dropped. */
+    minPresence?: number;
+}
+/** Inference report for a single field. */
+export interface FieldReport {
+    name: string;
+    sourcePath: string;
+    category: "identifier" | "classifier" | "numeric" | "text" | "other";
+    inferredType: FieldTypeDef;
+    presenceRate: number;
+    uniqueCount: number;
+    sampleCount: number;
+    isGroupKeyCandidate: boolean;
+}
+/** Result of schema generation — inspectable before committing. */
+export interface SchemaDraft {
+    schema: DcpSchemaDef;
+    mapping: FieldMappingDef;
+    fieldReports: FieldReport[];
+}
+/** Encoded DCP output. */
+export interface EncodedBatch {
+    header: string;
+    rows: string[];
+    schemaId: string;
+    mask: number;
+    isCutdown: boolean;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}