@scotthuang/agent-knock-knock 0.1.0

package/dist/src/runtime-log.js

@@ -0,0 +1,149 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+const DEFAULT_RETENTION_DAYS = 14;
+const LOG_LEVELS = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+    silent: Number.POSITIVE_INFINITY
+};
+const SENSITIVE_KEY_PATTERN = /(authorization|api[_-]?key|token|secret|password|passwd|gatewayToken|proxy|allProxy)/i;
+const cleanupPerformed = new Set();
+export function defaultRuntimeLogDir() {
+    return path.join(os.homedir(), ".agent-knock-knock", "logs");
+}
+export function localDateStamp(date = new Date()) {
+    return [
+        date.getFullYear(),
+        pad(date.getMonth() + 1),
+        pad(date.getDate())
+    ].join("-");
+}
+export function localTimestamp(date = new Date()) {
+    return `${localDateStamp(date)}T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}.${pad(date.getMilliseconds(), 3)}${timezoneOffset(date)}`;
+}
+export function runtimeLogPath({ now = new Date(), logDir = defaultRuntimeLogDir() } = {}) {
+    return path.join(expandHome(logDir), `runtime-${localDateStamp(now)}.ndjson`);
+}
+export function writeRuntimeLog(record, options = {}) {
+    const level = normalizeLevel(record.level ?? "info");
+    const configuredLevel = normalizeLevel(options.level ?? process.env.AKK_LOG_LEVEL ?? "info");
+    if (!shouldLog(level, configuredLevel)) {
+        return { written: false };
+    }
+    const now = options.now ?? new Date();
+    const logDir = expandHome(options.logDir ?? process.env.AKK_LOG_DIR ?? defaultRuntimeLogDir());
+    const retentionDays = retentionDaysFromOptions(options);
+    maybeCleanupRuntimeLogs({ logDir, retentionDays, now });
+    fs.mkdirSync(logDir, { recursive: true });
+    const logPath = runtimeLogPath({ now, logDir });
+    const entry = redactRecord({
+        ts: localTimestamp(now),
+        ts_utc: now.toISOString(),
+        level,
+        ...record
+    });
+    fs.appendFileSync(logPath, `${JSON.stringify(entry)}\n`, "utf8");
+    return { written: true, path: logPath, entry };
+}
+export function cleanupRuntimeLogs({ logDir = defaultRuntimeLogDir(), retentionDays = DEFAULT_RETENTION_DAYS, now = new Date() } = {}) {
+    const expandedLogDir = expandHome(logDir);
+    const retention = Number(retentionDays);
+    if (!Number.isFinite(retention) || retention <= 0 || !fs.existsSync(expandedLogDir)) {
+        return { checked: 0, deleted: 0, retention_days: retention };
+    }
+    const cutoffMs = startOfLocalDay(now).getTime() - (retention * 24 * 60 * 60 * 1000);
+    let checked = 0;
+    let deleted = 0;
+    for (const entry of fs.readdirSync(expandedLogDir, { withFileTypes: true })) {
+        if (!entry.isFile()) {
+            continue;
+        }
+        const match = /^runtime-(\d{4})-(\d{2})-(\d{2})\.ndjson$/.exec(entry.name);
+        if (!match) {
+            continue;
+        }
+        checked += 1;
+        const fileDay = new Date(Number(match[1]), Number(match[2]) - 1, Number(match[3]));
+        if (fileDay.getTime() < cutoffMs) {
+            fs.rmSync(path.join(expandedLogDir, entry.name), { force: true });
+            deleted += 1;
+        }
+    }
+    return { checked, deleted, retention_days: retention };
+}
+export function redactRecord(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => redactRecord(item));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => {
+            if (SENSITIVE_KEY_PATTERN.test(key)) {
+                return [key, "[REDACTED]"];
+            }
+            return [key, redactRecord(item)];
+        }));
+    }
+    if (typeof value === "string") {
+        return redactString(value);
+    }
+    return value;
+}
+export function redactString(value) {
+    return String(value)
+        .replace(/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, "Bearer [REDACTED]")
+        .replace(/(--(?:gateway-)?token(?:=|\s+))("[^"]+"|'[^']+'|\S+)/gi, "$1[REDACTED]")
+        .replace(/\bsk-[A-Za-z0-9_-]{12,}\b/g, "sk-[REDACTED]")
+        .replace(/\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g, "gh[REDACTED]")
+        .replace(/\bgithub_pat_[A-Za-z0-9_]{20,}\b/g, "github_pat_[REDACTED]")
+        .replace(/\bAKIA[0-9A-Z]{16}\b/g, "AKIA[REDACTED]")
+        .replace(/-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g, "[REDACTED PRIVATE KEY]")
+        .replace(/\b([a-z][a-z0-9+.-]*:\/\/)([^/\s:@]+):([^@\s/]+)@/gi, "$1[REDACTED]@");
+}
+function maybeCleanupRuntimeLogs({ logDir, retentionDays, now }) {
+    const key = `${path.resolve(logDir)}:${retentionDays}`;
+    if (cleanupPerformed.has(key)) {
+        return;
+    }
+    cleanupPerformed.add(key);
+    cleanupRuntimeLogs({ logDir, retentionDays, now });
+}
+function retentionDaysFromOptions(options) {
+    if (options.retentionDays !== undefined) {
+        return Number(options.retentionDays);
+    }
+    if (process.env.AKK_LOG_RETENTION_DAYS !== undefined) {
+        return Number(process.env.AKK_LOG_RETENTION_DAYS);
+    }
+    return DEFAULT_RETENTION_DAYS;
+}
+function normalizeLevel(level) {
+    return typeof level === "string" && Object.hasOwn(LOG_LEVELS, level) ? level : "info";
+}
+function shouldLog(level, configuredLevel) {
+    return LOG_LEVELS[level] >= LOG_LEVELS[configuredLevel];
+}
+function startOfLocalDay(date) {
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate());
+}
+function timezoneOffset(date) {
+    const offsetMinutes = -date.getTimezoneOffset();
+    const sign = offsetMinutes >= 0 ? "+" : "-";
+    const absolute = Math.abs(offsetMinutes);
+    return `${sign}${pad(Math.floor(absolute / 60))}:${pad(absolute % 60)}`;
+}
+function pad(value, size = 2) {
+    return String(value).padStart(size, "0");
+}
+function expandHome(filePath) {
+    if (filePath === "~") {
+        return os.homedir();
+    }
+    if (filePath?.startsWith("~/")) {
+        return path.join(os.homedir(), filePath.slice(2));
+    }
+    return filePath;
+}
+//# sourceMappingURL=runtime-log.js.map

package/dist/src/runtime-log.js.map

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

package/dist/src/store.d.ts

@@ -0,0 +1,35 @@
+import type { AgentMessage, Conversation } from "./protocol.js";
+export declare function defaultStoreDir(_workspace?: string): string;
+export declare function defaultLogDir(workspace?: string): string;
+export declare function ensureDir(dir: string): void;
+export interface ConversationPaths {
+    storeDir: string;
+    logDir: string;
+    conversationDir: string;
+    logPath: string;
+    statePath: string;
+}
+export interface EventRecord {
+    event: string;
+    [key: string]: unknown;
+}
+export declare function pathsForConversation(conversationId: string, storeDir?: string): ConversationPaths;
+export declare function pathsForConversationDir(conversationDir: string): ConversationPaths;
+export declare function logPathForStatePath(statePath: string): string;
+export declare function saveState(statePath: string, conversation: Conversation): void;
+export declare function loadState(statePath: string): Conversation;
+export declare function statePathForConversationId(conversationId: string, storeDir?: string): string;
+export declare function loadConversationById(conversationId: string, storeDir?: string): Conversation;
+export declare function listConversations(storeDir?: string): Conversation[];
+export declare function appendEvent(logPath: string, event: EventRecord): void;
+export declare function assertAppendableEventLog(logPath: string): true;
+export declare function messageEvent(message: AgentMessage): EventRecord;
+export declare function rawExchangeEvent({ conversationId, from, to, prompt, response, round, type }: {
+    conversationId: string;
+    from: string;
+    to: string;
+    prompt: string;
+    response: string;
+    round: number;
+    type?: string;
+}): EventRecord;

package/dist/src/store.js

@@ -0,0 +1,121 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function defaultStoreDir(_workspace = process.cwd()) {
+    return path.join(os.homedir(), ".agent-knock-knock", "conversations");
+}
+export function defaultLogDir(workspace = process.cwd()) {
+    return defaultStoreDir(workspace);
+}
+export function ensureDir(dir) {
+    fs.mkdirSync(dir, { recursive: true });
+}
+export function pathsForConversation(conversationId, storeDir = defaultStoreDir()) {
+    const conversationDir = path.join(storeDir, conversationId);
+    return {
+        storeDir,
+        logDir: storeDir,
+        conversationDir,
+        logPath: path.join(conversationDir, "events.ndjson"),
+        statePath: path.join(conversationDir, "state.json")
+    };
+}
+export function pathsForConversationDir(conversationDir) {
+    return {
+        storeDir: path.dirname(conversationDir),
+        logDir: path.dirname(conversationDir),
+        conversationDir,
+        logPath: path.join(conversationDir, "events.ndjson"),
+        statePath: path.join(conversationDir, "state.json")
+    };
+}
+export function logPathForStatePath(statePath) {
+    if (path.basename(statePath) === "state.json") {
+        return path.join(path.dirname(statePath), "events.ndjson");
+    }
+    return statePath.replace(/\.state\.json$/, ".ndjson");
+}
+export function saveState(statePath, conversation) {
+    ensureDir(path.dirname(statePath));
+    fs.writeFileSync(statePath, `${JSON.stringify(conversation, null, 2)}\n`, "utf8");
+}
+export function loadState(statePath) {
+    return JSON.parse(fs.readFileSync(statePath, "utf8"));
+}
+export function statePathForConversationId(conversationId, storeDir = defaultStoreDir()) {
+    return path.join(storeDir, conversationId, "state.json");
+}
+export function loadConversationById(conversationId, storeDir = defaultStoreDir()) {
+    return loadState(statePathForConversationId(conversationId, storeDir));
+}
+export function listConversations(storeDir = defaultStoreDir()) {
+    if (!fs.existsSync(storeDir)) {
+        return [];
+    }
+    return fs.readdirSync(storeDir, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory())
+        .map((entry) => path.join(storeDir, entry.name, "state.json"))
+        .filter((statePath) => fs.existsSync(statePath))
+        .map((statePath) => {
+        const conversation = loadState(statePath);
+        return {
+            ...conversation,
+            state_path: conversation.state_path ?? statePath,
+            event_log_path: conversation.event_log_path ?? logPathForStatePath(statePath),
+            conversation_dir: conversation.conversation_dir ?? path.dirname(statePath)
+        };
+    })
+        .sort((left, right) => String(right.updated_at ?? "").localeCompare(String(left.updated_at ?? "")));
+}
+export function appendEvent(logPath, event) {
+    ensureDir(path.dirname(logPath));
+    assertAppendableEventLog(logPath);
+    fs.appendFileSync(logPath, `${JSON.stringify(event)}\n`, "utf8");
+}
+export function assertAppendableEventLog(logPath) {
+    if (!fs.existsSync(logPath)) {
+        return true;
+    }
+    const text = fs.readFileSync(logPath, "utf8");
+    const lines = text.split(/\r?\n/).filter((line) => line.trim().length > 0);
+    for (const [index, line] of lines.entries()) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch (error) {
+            throw new Error(`event log is not valid NDJSON at line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (!parsed || typeof parsed !== "object" || Array.isArray(parsed) || typeof parsed.event !== "string") {
+            throw new Error(`event log line ${index + 1} is not an event object`);
+        }
+    }
+    return true;
+}
+export function messageEvent(message) {
+    return {
+        ts: message.ts,
+        conversation_id: message.conversation_id,
+        event: "message",
+        from: message.from,
+        to: message.to,
+        type: message.type,
+        requires_response: message.requires_response,
+        round: message.round,
+        body: message.body,
+        message
+    };
+}
+export function rawExchangeEvent({ conversationId, from, to, prompt, response, round, type = "raw_exchange" }) {
+    return {
+        ts: new Date().toISOString(),
+        conversation_id: conversationId,
+        event: type,
+        from,
+        to,
+        round,
+        prompt,
+        response
+    };
+}
+//# sourceMappingURL=store.js.map

package/dist/src/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../src/store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,MAAM,UAAU,eAAe,CAAC,UAAU,GAAG,OAAO,CAAC,GAAG,EAAE;IACxD,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,oBAAoB,EAAE,eAAe,CAAC,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,SAAS,GAAG,OAAO,CAAC,GAAG,EAAE;IACrD,OAAO,eAAe,CAAC,SAAS,CAAC,CAAC;AACpC,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,GAAW;IACnC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;AACzC,CAAC;AAeD,MAAM,UAAU,oBAAoB,CAAC,cAAsB,EAAE,QAAQ,GAAG,eAAe,EAAE;IACvF,MAAM,eAAe,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,cAAc,CAAC,CAAC;IAC5D,OAAO;QACL,QAAQ;QACR,MAAM,EAAE,QAAQ;QAChB,eAAe;QACf,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,eAAe,CAAC;QACpD,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,YAAY,CAAC;KACpD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,uBAAuB,CAAC,eAAuB;IAC7D,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC;QACvC,MAAM,EAAE,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC;QACrC,eAAe;QACf,OAAO,EAAE,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,eAAe,CAAC;QACpD,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,eAAe,EAAE,YAAY,CAAC;KACpD,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,mBAAmB,CAAC,SAAiB;IACnD,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,YAAY,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EAAE,eAAe,CAAC,CAAC;IAC7D,CAAC;IAED,OAAO,SAAS,CAAC,OAAO,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,SAAiB,EAAE,YAA0B;IACrE,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC;IACnC,EAAE,CAAC,aAAa,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACpF,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,SAAiB;IACzC,OAAO,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAiB,CAAC;AACxE,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,cAAsB,EAAE,QAAQ,GAAG,eAAe,EAAE;IAC7F,OAAO,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,cAAc,EAAE,YAAY,CAAC,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,cAAsB,EAAE,QAAQ,GAAG,eAAe,EAAE;IACvF,OAAO,SAAS,CAAC,0BAA0B,CAAC,cAAc,EAAE,QAAQ,CAAC,CAAC,CAAC;AACzE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,QAAQ,GAAG,eAAe,EAAE;IAC5D,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,EAAE,CAAC,WAAW,CAAC,QAAQ,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;SACrD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC;SACtC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;SAC7D,MAAM,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;SAC/C,GAAG,CAAC,CAAC,SAAS,EAAE,EAAE;QACjB,MAAM,YAAY,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;QAC1C,OAAO;YACL,GAAG,YAAY;YACf,UAAU,EAAE,YAAY,CAAC,UAAU,IAAI,SAAS;YAChD,cAAc,EAAE,YAAY,CAAC,cAAc,IAAI,mBAAmB,CAAC,SAAS,CAAC;YAC7E,gBAAgB,EAAE,YAAY,CAAC,gBAAgB,IAAI,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC;SAC3E,CAAC;IACJ,CAAC,CAAC;SACD,IAAI,CAAC,CAAC,IAAkB,EAAE,KAAmB,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;AACpI,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,KAAkB;IAC7D,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;IACjC,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAClC,EAAE,CAAC,cAAc,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;AACnE,CAAC;AAED,MAAM,UAAU,wBAAwB,CAAC,OAAe;IACtD,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5B,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC9C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAE3E,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,KAAK,CAAC,OAAO,EAAE,EAAE,CAAC;QAC5C,IAAI,MAAM,CAAC;QACX,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,yCAAyC,KAAK,GAAG,CAAC,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACnI,CAAC;QAED,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,IAAI,OAAO,MAAM,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;YACvG,MAAM,IAAI,KAAK,CAAC,kBAAkB,KAAK,GAAG,CAAC,yBAAyB,CAAC,CAAC;QACxE,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,OAAqB;IAChD,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,eAAe,EAAE,OAAO,CAAC,eAAe;QACxC,KAAK,EAAE,SAAS;QAChB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,EAAE,EAAE,OAAO,CAAC,EAAE;QACd,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,iBAAiB,EAAE,OAAO,CAAC,iBAAiB;QAC5C,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,OAAO;KACR,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,EAC/B,cAAc,EACd,IAAI,EACJ,EAAE,EACF,MAAM,EACN,QAAQ,EACR,KAAK,EACL,IAAI,GAAG,cAAc,EAStB;IACC,OAAO;QACL,EAAE,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QAC5B,eAAe,EAAE,cAAc;QAC/B,KAAK,EAAE,IAAI;QACX,IAAI;QACJ,EAAE;QACF,KAAK;QACL,MAAM;QACN,QAAQ;KACT,CAAC;AACJ,CAAC"}

package/dist/src/transcript.d.ts

@@ -0,0 +1,24 @@
+export interface TranscriptEvent {
+    event?: string;
+    conversation?: Record<string, unknown>;
+    conversation_id?: string;
+    from?: string;
+    to?: string;
+    type?: string;
+    round?: number;
+    requires_response?: boolean;
+    body?: string;
+    status?: string;
+    response_rounds_used?: number;
+    manager_final?: string;
+    response?: string;
+    tool_name?: string;
+    permission?: string;
+    source?: string;
+    [key: string]: unknown;
+}
+export declare function readNdjsonLog(logPath: string): TranscriptEvent[];
+export declare function parseNdjson(text: string): TranscriptEvent[];
+export declare function formatTranscript(events: TranscriptEvent[], { includeRaw }?: {
+    includeRaw?: boolean;
+}): string;

package/dist/src/transcript.js

@@ -0,0 +1,88 @@
+import fs from "node:fs";
+export function readNdjsonLog(logPath) {
+    const text = fs.readFileSync(logPath, "utf8");
+    return parseNdjson(text);
+}
+export function parseNdjson(text) {
+    return text
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .map((line, index) => {
+        try {
+            return JSON.parse(line);
+        }
+        catch (error) {
+            throw new Error(`invalid NDJSON at line ${index + 1}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+}
+export function formatTranscript(events, { includeRaw = false } = {}) {
+    const lines = [];
+    for (const event of events) {
+        if (event.event === "conversation_created") {
+            lines.push(formatConversationCreated(event));
+        }
+        else if (event.event === "message" && event.source !== "normalized_acpx") {
+            lines.push(formatMessage(event));
+        }
+        else if (event.event === "conversation_closed") {
+            lines.push(formatConversationClosed(event));
+        }
+        else if (includeRaw && isDebugEvent(event)) {
+            lines.push(formatRawEvent(event));
+        }
+    }
+    return `${lines.filter(Boolean).join("\n\n")}\n`;
+}
+function formatConversationCreated(event) {
+    const conversation = event.conversation;
+    const id = event.conversation_id ?? conversation?.conversation_id ?? "unknown";
+    const status = typeof conversation?.status === "string" ? ` status=${conversation.status}` : "";
+    const request = typeof conversation?.user_request === "string" ? `\nRequest: ${conversation.user_request}` : "";
+    return `[conversation_created] ${id}${status}${request}`;
+}
+function formatMessage(event) {
+    const label = `${event.from} -> ${event.to}`;
+    const flags = [
+        `type=${event.type}`,
+        `round=${event.round}`,
+        `requires_response=${event.requires_response}`
+    ].join(" ");
+    return `[message] ${label} ${flags}\n${indent(event.body)}`;
+}
+function formatConversationClosed(event) {
+    const parts = [
+        `status=${event.status ?? "unknown"}`,
+        `rounds=${event.response_rounds_used ?? "unknown"}`
+    ];
+    const final = event.manager_final ? `\n${indent(event.manager_final)}` : "";
+    return `[conversation_closed] ${parts.join(" ")}${final}`;
+}
+function formatRawEvent(event) {
+    const label = `${event.from ?? "unknown"} -> ${event.to ?? "unknown"}`;
+    const details = [
+        event.type ? `type=${event.type}` : null,
+        event.status ? `status=${event.status}` : null,
+        event.tool_name ? `tool=${event.tool_name}` : null,
+        event.permission ? `permission=${event.permission}` : null
+    ].filter(Boolean);
+    const suffix = details.length > 0 ? ` ${details.join(" ")}` : "";
+    const body = event.response ?? event.body;
+    const formattedBody = body ? `\n${indent(body)}` : "";
+    return `[${event.event}] ${label} round=${event.round ?? "unknown"}${suffix}${formattedBody}`;
+}
+function isDebugEvent(event) {
+    return event.event === "raw_exchange" ||
+        event.event?.startsWith("developer_step_") ||
+        event.event?.startsWith("manager_step_") ||
+        event.event === "manager_final" ||
+        event.source === "normalized_acpx";
+}
+function indent(value) {
+    return String(value)
+        .split(/\r?\n/)
+        .map((line) => `  ${line}`)
+        .join("\n");
+}
+//# sourceMappingURL=transcript.js.map

package/dist/src/transcript.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transcript.js","sourceRoot":"","sources":["../../src/transcript.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AAsBzB,MAAM,UAAU,aAAa,CAAC,OAAe;IAC3C,MAAM,IAAI,GAAG,EAAE,CAAC,YAAY,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC9C,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;AAC3B,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,OAAO,IAAI;SACR,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,OAAO,CAAC;SACf,GAAG,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QACnB,IAAI,CAAC;YACH,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,0BAA0B,KAAK,GAAG,CAAC,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACpH,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAyB,EAAE,EAAE,UAAU,GAAG,KAAK,KAA+B,EAAE;IAC/G,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,IAAI,KAAK,CAAC,KAAK,KAAK,sBAAsB,EAAE,CAAC;YAC3C,KAAK,CAAC,IAAI,CAAC,yBAAyB,CAAC,KAAK,CAAC,CAAC,CAAC;QAC/C,CAAC;aAAM,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,iBAAiB,EAAE,CAAC;YAC3E,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC;QACnC,CAAC;aAAM,IAAI,KAAK,CAAC,KAAK,KAAK,qBAAqB,EAAE,CAAC;YACjD,KAAK,CAAC,IAAI,CAAC,wBAAwB,CAAC,KAAK,CAAC,CAAC,CAAC;QAC9C,CAAC;aAAM,IAAI,UAAU,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE,CAAC;YAC7C,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAED,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;AACnD,CAAC;AAED,SAAS,yBAAyB,CAAC,KAAsB;IACvD,MAAM,YAAY,GAAG,KAAK,CAAC,YAAY,CAAC;IACxC,MAAM,EAAE,GAAG,KAAK,CAAC,eAAe,IAAI,YAAY,EAAE,eAAe,IAAI,SAAS,CAAC;IAC/E,MAAM,MAAM,GAAG,OAAO,YAAY,EAAE,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,YAAY,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAChG,MAAM,OAAO,GAAG,OAAO,YAAY,EAAE,YAAY,KAAK,QAAQ,CAAC,CAAC,CAAC,cAAc,YAAY,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAChH,OAAO,0BAA0B,EAAE,GAAG,MAAM,GAAG,OAAO,EAAE,CAAC;AAC3D,CAAC;AAED,SAAS,aAAa,CAAC,KAAsB;IAC3C,MAAM,KAAK,GAAG,GAAG,KAAK,CAAC,IAAI,OAAO,KAAK,CAAC,EAAE,EAAE,CAAC;IAC7C,MAAM,KAAK,GAAG;QACZ,QAAQ,KAAK,CAAC,IAAI,EAAE;QACpB,SAAS,KAAK,CAAC,KAAK,EAAE;QACtB,qBAAqB,KAAK,CAAC,iBAAiB,EAAE;KAC/C,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAEZ,OAAO,aAAa,KAAK,IAAI,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED,SAAS,wBAAwB,CAAC,KAAsB;IACtD,MAAM,KAAK,GAAG;QACZ,UAAU,KAAK,CAAC,MAAM,IAAI,SAAS,EAAE;QACrC,UAAU,KAAK,CAAC,oBAAoB,IAAI,SAAS,EAAE;KACpD,CAAC;IACF,MAAM,KAAK,GAAG,KAAK,CAAC,aAAa,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC5E,OAAO,yBAAyB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,KAAK,EAAE,CAAC;AAC5D,CAAC;AAED,SAAS,cAAc,CAAC,KAAsB;IAC5C,MAAM,KAAK,GAAG,GAAG,KAAK,CAAC,IAAI,IAAI,SAAS,OAAO,KAAK,CAAC,EAAE,IAAI,SAAS,EAAE,CAAC;IACvE,MAAM,OAAO,GAAG;QACd,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,QAAQ,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI;QACxC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,UAAU,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,IAAI;QAC9C,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,KAAK,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI;QAClD,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,cAAc,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,IAAI;KAC3D,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAClB,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACjE,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC;IAC1C,MAAM,aAAa,GAAG,IAAI,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACtD,OAAO,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK,UAAU,KAAK,CAAC,KAAK,IAAI,SAAS,GAAG,MAAM,GAAG,aAAa,EAAE,CAAC;AAChG,CAAC;AAED,SAAS,YAAY,CAAC,KAAsB;IAC1C,OAAO,KAAK,CAAC,KAAK,KAAK,cAAc;QACnC,KAAK,CAAC,KAAK,EAAE,UAAU,CAAC,iBAAiB,CAAC;QAC1C,KAAK,CAAC,KAAK,EAAE,UAAU,CAAC,eAAe,CAAC;QACxC,KAAK,CAAC,KAAK,KAAK,eAAe;QAC/B,KAAK,CAAC,MAAM,KAAK,iBAAiB,CAAC;AACvC,CAAC;AAED,SAAS,MAAM,CAAC,KAAc;IAC5B,OAAO,MAAM,CAAC,KAAK,CAAC;SACjB,KAAK,CAAC,OAAO,CAAC;SACd,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC;SAC1B,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/openclaw.plugin.json

@@ -0,0 +1,150 @@
+{
+  "id": "agent-knock-knock",
+  "name": "Agent Knock Knock",
+  "description": "Agent Knock Knock (AKK/akk) delegates OpenClaw coding work to local Codex, Claude, or Cursor agents. Use this plugin when the user says AKK, akk, Agent Knock Knock, asks to hand work to Codex, Claude, or Cursor, asks what agent tasks are running, sends a follow-up to an agent task, recovers or restarts an unavailable agent session, cancels a running agent task, or closes an agent task. Default delegation target comes from plugin config defaultAgent and falls back to Codex when unset; explicit user agent requests override it.",
+  "activation": {
+    "onStartup": true
+  },
+  "contracts": {
+    "commands": [
+      "akk"
+    ],
+    "tools": [
+      "agent_knock_knock_delegate",
+      "agent_knock_knock_list",
+      "agent_knock_knock_status",
+      "agent_knock_knock_send",
+      "agent_knock_knock_cancel",
+      "agent_knock_knock_recover",
+      "agent_knock_knock_restart",
+      "agent_knock_knock_close"
+    ]
+  },
+  "toolMetadata": {
+    "agent_knock_knock_delegate": {
+      "optional": true
+    },
+    "agent_knock_knock_list": {
+      "optional": true
+    },
+    "agent_knock_knock_status": {
+      "optional": true
+    },
+    "agent_knock_knock_send": {
+      "optional": true
+    },
+    "agent_knock_knock_cancel": {
+      "optional": true
+    },
+    "agent_knock_knock_recover": {
+      "optional": true
+    },
+    "agent_knock_knock_restart": {
+      "optional": true
+    },
+    "agent_knock_knock_close": {
+      "optional": true
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "binPath": {
+        "type": "string",
+        "description": "Path to agent-knock-knock CLI. Defaults to this package's dist/src/cli.js build output."
+      },
+      "workspace": {
+        "type": "string",
+        "description": "Default workspace for delegated coding-agent tasks."
+      },
+      "storeDir": {
+        "type": "string",
+        "description": "Default conversation store directory."
+      },
+      "claudeSession": {
+        "type": "string",
+        "description": "Default Claude Code session name."
+      },
+      "codexSession": {
+        "type": "string",
+        "description": "Default Codex session name."
+      },
+      "cursorSession": {
+        "type": "string",
+        "description": "Default Cursor session name."
+      },
+      "defaultAgent": {
+        "type": "string",
+        "enum": ["claude", "codex", "cursor"],
+        "description": "Default coding agent for unspecified AKK delegations. If unset, Agent Knock Knock falls back to codex."
+      },
+      "defaultClaudeSession": {
+        "type": "string",
+        "description": "Default Claude Code session name. claudeSession remains supported as a compatibility alias."
+      },
+      "defaultCodexSession": {
+        "type": "string",
+        "description": "Default Codex session name."
+      },
+      "defaultCursorSession": {
+        "type": "string",
+        "description": "Default Cursor session name."
+      },
+      "codexAllProxy": {
+        "type": "string",
+        "description": "ALL_PROXY value used when launching Codex through ACPX."
+      },
+      "cursorAllProxy": {
+        "type": "string",
+        "description": "ALL_PROXY value used when launching Cursor through ACPX."
+      },
+      "codexModel": {
+        "type": "string",
+        "description": "ACPX model id used when launching Codex."
+      },
+      "cursorModel": {
+        "type": "string",
+        "description": "ACPX model id used when launching Cursor."
+      },
+      "model": {
+        "type": "string",
+        "description": "ACPX model id used when launching coding agents."
+      },
+      "allProxy": {
+        "type": "string",
+        "description": "ALL_PROXY value used when launching coding agents through ACPX."
+      },
+      "openclawSession": {
+        "type": "string",
+        "description": "Default OpenClaw session label stored in the protocol state."
+      },
+      "gatewayUrl": {
+        "type": "string",
+        "description": "Gateway URL used by the legacy CLI callback delivery path."
+      },
+      "gatewayToken": {
+        "type": "string",
+        "description": "Gateway token used by the legacy CLI callback delivery path."
+      },
+      "openclawBin": {
+        "type": "string",
+        "description": "Path to the OpenClaw CLI used by callback delivery. Defaults to PATH plus common user install locations."
+      },
+      "callbackCommand": {
+        "type": "string",
+        "description": "Optional callback command template. {statePath} and {state_path} are replaced with the shell-quoted state path."
+      },
+      "idleTimeoutMinutes": {
+        "type": "number",
+        "description": "Minutes an idle AKK session remains open before lazy cleanup closes it. Defaults to 10080."
+      },
+      "softLimit": {
+        "type": "number"
+      },
+      "hardLimit": {
+        "type": "number"
+      }
+    }
+  }
+}

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@scotthuang/agent-knock-knock",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin bridge for delegating work to local coding agents through ACPX.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://github.com/scotthuang/agent-knock-knock#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/scotthuang/agent-knock-knock.git"
+  },
+  "bugs": {
+    "url": "https://github.com/scotthuang/agent-knock-knock/issues"
+  },
+  "keywords": [
+    "openclaw",
+    "acpx",
+    "codex",
+    "claude-code",
+    "cursor",
+    "coding-agent"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./dist/src/openclaw-plugin.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    }
+  },
+  "bin": {
+    "agent-knock-knock": "dist/src/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "templates",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "clean": "node -e \"fs.rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "prepack": "npm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test dist/test/*.test.js",
+    "simulate:architecture": "node scripts/two-claude-weather-test.js --scenario architecture-questions",
+    "simulate:weather": "node scripts/two-claude-weather-test.js --scenario weather",
+    "transcript": "node dist/src/cli.js transcript"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "typescript": "^6.0.3"
+  }
+}