@workflow-cannon/workspace-kit 0.6.0 → 0.8.0

package/dist/core/response-template-registry.d.ts

@@ -0,0 +1,4 @@
+import type { ResponseTemplateDefinition } from "./response-template-contract.js";
+export declare function getResponseTemplateDefinition(id: string | undefined): ResponseTemplateDefinition | undefined;
+export declare function listBuiltinResponseTemplateIds(): string[];
+export declare function allBuiltinDefinitions(): ResponseTemplateDefinition[];

package/dist/core/response-template-registry.js

@@ -0,0 +1,44 @@
+const BUILTIN = {
+    default: {
+        id: "default",
+        version: 1,
+        scope: "global",
+        description: "Passthrough with standard ok/code/message/data fields.",
+        expectedSections: ["ok", "code", "message", "data"]
+    },
+    compact: {
+        id: "compact",
+        version: 1,
+        scope: "global",
+        description: "Emphasizes top-level code and message for quick scanning.",
+        expectedSections: ["ok", "code", "message"]
+    },
+    completed_task: {
+        id: "completed_task",
+        version: 1,
+        scope: "command",
+        description: "Structured completion-style surface for task-style commands.",
+        expectedSections: ["ok", "code", "message", "data"]
+    },
+    COMPLETED_TASK: {
+        id: "COMPLETED_TASK",
+        version: 1,
+        scope: "command",
+        description: "Alias id matching plain-English directive spelling.",
+        expectedSections: ["ok", "code", "message", "data"]
+    }
+};
+export function getResponseTemplateDefinition(id) {
+    if (!id || typeof id !== "string")
+        return undefined;
+    const trimmed = id.trim();
+    if (!trimmed)
+        return undefined;
+    return BUILTIN[trimmed] ?? BUILTIN[trimmed.toLowerCase()] ?? undefined;
+}
+export function listBuiltinResponseTemplateIds() {
+    return Object.keys(BUILTIN).sort((a, b) => a.localeCompare(b));
+}
+export function allBuiltinDefinitions() {
+    return Object.values(BUILTIN);
+}

package/dist/core/response-template-shaping.d.ts

@@ -0,0 +1,6 @@
+import type { ModuleCommandResult } from "../contracts/module-contract.js";
+/**
+ * Apply response template metadata and optional presentation hints (T262, T265).
+ * Advisory mode never flips `ok`. Strict mode fails closed on unknown template ids when a template was explicitly requested or command override is set.
+ */
+export declare function applyResponseTemplateApplication(commandName: string, args: Record<string, unknown>, result: ModuleCommandResult, effective: Record<string, unknown>): ModuleCommandResult;

package/dist/core/response-template-shaping.js

@@ -0,0 +1,128 @@
+import { truncateTemplateWarning } from "./response-template-contract.js";
+import { getResponseTemplateDefinition } from "./response-template-registry.js";
+import { parseTemplateDirectiveFromText } from "./instruction-template-mapper.js";
+function readResponseTemplatesConfig(effective) {
+    const rt = effective.responseTemplates;
+    if (!rt || typeof rt !== "object" || Array.isArray(rt)) {
+        return { enforcementMode: "advisory", defaultTemplateId: "default", commandOverrides: {} };
+    }
+    const o = rt;
+    const modeRaw = o.enforcementMode;
+    const enforcementMode = modeRaw === "strict" ? "strict" : "advisory";
+    const defRaw = o.defaultTemplateId;
+    const def = typeof defRaw === "string" && defRaw.trim().length > 0 ? defRaw.trim() : "default";
+    const commandOverrides = {};
+    const co = o.commandOverrides;
+    if (co && typeof co === "object" && !Array.isArray(co)) {
+        for (const [k, v] of Object.entries(co)) {
+            if (typeof v === "string" && v.trim()) {
+                commandOverrides[k.trim()] = v.trim();
+            }
+        }
+    }
+    return { enforcementMode, defaultTemplateId: def, commandOverrides };
+}
+function resolveRequestedTemplateId(commandName, args) {
+    const parseWarnings = [];
+    const explicit = typeof args.responseTemplateId === "string" && args.responseTemplateId.trim()
+        ? args.responseTemplateId.trim()
+        : null;
+    const directiveSources = [
+        typeof args.responseTemplateDirective === "string" ? args.responseTemplateDirective : "",
+        typeof args.instructionTemplateDirective === "string" ? args.instructionTemplateDirective : "",
+        typeof args.instruction === "string" ? args.instruction : ""
+    ].filter(Boolean);
+    let fromText = null;
+    for (const src of directiveSources) {
+        const parsed = parseTemplateDirectiveFromText(src);
+        parseWarnings.push(...parsed.warnings);
+        if (parsed.templateId) {
+            fromText = parsed.templateId;
+            break;
+        }
+    }
+    if (explicit && fromText && explicit !== fromText) {
+        parseWarnings.push(truncateTemplateWarning(`responseTemplateId '${explicit}' disagrees with instruction directive '${fromText}'; using explicit id.`));
+    }
+    if (explicit)
+        return { templateId: explicit, parseWarnings };
+    if (fromText)
+        return { templateId: fromText, parseWarnings };
+    return { templateId: null, parseWarnings };
+}
+function attachPresentation(templateId, result) {
+    const def = getResponseTemplateDefinition(templateId);
+    if (!def || !result.data || typeof result.data !== "object" || Array.isArray(result.data)) {
+        return undefined;
+    }
+    const data = result.data;
+    const matchedSections = def.expectedSections.filter((k) => k in data);
+    return {
+        templateId: def.id,
+        matchedSections
+    };
+}
+function buildMeta(partial, startNs) {
+    const warningCount = partial.warnings.length;
+    return {
+        ...partial,
+        telemetry: {
+            resolveNs: Number(process.hrtime.bigint() - startNs),
+            warningCount
+        }
+    };
+}
+/**
+ * Apply response template metadata and optional presentation hints (T262, T265).
+ * Advisory mode never flips `ok`. Strict mode fails closed on unknown template ids when a template was explicitly requested or command override is set.
+ */
+export function applyResponseTemplateApplication(commandName, args, result, effective) {
+    const startNs = process.hrtime.bigint();
+    const cfg = readResponseTemplatesConfig(effective);
+    const { templateId: requestedRaw, parseWarnings } = resolveRequestedTemplateId(commandName, args);
+    const override = cfg.commandOverrides[commandName];
+    const chosenId = requestedRaw ?? override ?? cfg.defaultTemplateId ?? "default";
+    const warnings = [...parseWarnings];
+    const def = getResponseTemplateDefinition(chosenId);
+    if (!def) {
+        warnings.push(truncateTemplateWarning(`Unknown response template '${chosenId}'.`));
+        const explicitRequest = Boolean(requestedRaw || override);
+        if (cfg.enforcementMode === "strict" && explicitRequest) {
+            return {
+                ...result,
+                ok: false,
+                code: "response-template-invalid",
+                message: truncateTemplateWarning(`Unknown response template '${chosenId}'.`),
+                responseTemplate: buildMeta({
+                    requestedTemplateId: requestedRaw ?? override,
+                    appliedTemplateId: null,
+                    enforcementMode: cfg.enforcementMode,
+                    warnings
+                }, startNs)
+            };
+        }
+        return {
+            ...result,
+            responseTemplate: buildMeta({
+                requestedTemplateId: requestedRaw ?? override ?? cfg.defaultTemplateId,
+                appliedTemplateId: null,
+                enforcementMode: cfg.enforcementMode,
+                warnings
+            }, startNs)
+        };
+    }
+    const presentation = attachPresentation(def.id, result);
+    const nextData = presentation && result.data && typeof result.data === "object" && !Array.isArray(result.data)
+        ? { ...result.data, presentation }
+        : result.data;
+    return {
+        ...result,
+        data: nextData,
+        responseTemplate: buildMeta({
+            requestedTemplateId: requestedRaw ?? override ?? cfg.defaultTemplateId,
+            appliedTemplateId: def.id,
+            enforcementMode: cfg.enforcementMode,
+            warnings
+        }, startNs)
+    };
+}

package/dist/core/session-policy.d.ts

@@ -0,0 +1,18 @@
+import type { PolicyOperationId } from "./policy.js";
+export declare const SESSION_POLICY_SCHEMA_VERSION: 1;
+export type SessionPolicyGrant = {
+    rationale: string;
+    grantedAt: string;
+};
+export type SessionPolicyDocument = {
+    schemaVersion: typeof SESSION_POLICY_SCHEMA_VERSION;
+    /** Logical session id (override with WORKSPACE_KIT_SESSION_ID). */
+    sessionId: string;
+    /** Active grants for sensitive operations within this session file. */
+    grants: Partial<Record<PolicyOperationId, SessionPolicyGrant>>;
+};
+export declare function resolveSessionId(env: NodeJS.ProcessEnv): string;
+export declare function loadSessionPolicyDocument(workspacePath: string): Promise<SessionPolicyDocument>;
+export declare function saveSessionPolicyDocument(workspacePath: string, doc: SessionPolicyDocument): Promise<void>;
+export declare function getSessionGrant(workspacePath: string, operationId: PolicyOperationId, sessionId: string): Promise<SessionPolicyGrant | undefined>;
+export declare function recordSessionGrant(workspacePath: string, operationId: PolicyOperationId, sessionId: string, rationale: string): Promise<void>;

package/dist/core/session-policy.js

@@ -0,0 +1,57 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+export const SESSION_POLICY_SCHEMA_VERSION = 1;
+const REL = ".workspace-kit/policy/session-grants.json";
+function defaultDoc(sessionId) {
+    return {
+        schemaVersion: SESSION_POLICY_SCHEMA_VERSION,
+        sessionId,
+        grants: {}
+    };
+}
+export function resolveSessionId(env) {
+    const raw = env.WORKSPACE_KIT_SESSION_ID?.trim();
+    return raw && raw.length > 0 ? raw : "default";
+}
+export async function loadSessionPolicyDocument(workspacePath) {
+    const fp = path.join(workspacePath, REL);
+    try {
+        const raw = await fs.readFile(fp, "utf8");
+        const doc = JSON.parse(raw);
+        if (doc.schemaVersion !== SESSION_POLICY_SCHEMA_VERSION) {
+            return defaultDoc(resolveSessionId(process.env));
+        }
+        return {
+            ...defaultDoc(doc.sessionId ?? resolveSessionId(process.env)),
+            ...doc,
+            grants: doc.grants && typeof doc.grants === "object" ? doc.grants : {}
+        };
+    }
+    catch (e) {
+        if (e.code === "ENOENT") {
+            return defaultDoc(resolveSessionId(process.env));
+        }
+        throw e;
+    }
+}
+export async function saveSessionPolicyDocument(workspacePath, doc) {
+    const fp = path.join(workspacePath, REL);
+    await fs.mkdir(path.dirname(fp), { recursive: true });
+    await fs.writeFile(fp, `${JSON.stringify(doc, null, 2)}\n`, "utf8");
+}
+export async function getSessionGrant(workspacePath, operationId, sessionId) {
+    const doc = await loadSessionPolicyDocument(workspacePath);
+    if (doc.sessionId !== sessionId) {
+        return undefined;
+    }
+    return doc.grants[operationId];
+}
+export async function recordSessionGrant(workspacePath, operationId, sessionId, rationale) {
+    const doc = await loadSessionPolicyDocument(workspacePath);
+    doc.sessionId = sessionId;
+    doc.grants[operationId] = {
+        rationale,
+        grantedAt: new Date().toISOString()
+    };
+    await saveSessionPolicyDocument(workspacePath, doc);
+}

package/dist/core/transcript-completion-hook.d.ts

@@ -0,0 +1,7 @@
+export declare function readAfterTaskCompletedHook(effective: Record<string, unknown>): "off" | "sync" | "ingest";
+export declare function resolveWorkspaceKitCli(workspacePath: string): string | null;
+/**
+ * After a task reaches `completed`, optionally spawn sync/ingest without blocking the transition (T274).
+ * Ingest requires WORKSPACE_KIT_POLICY_APPROVAL in the parent env or falls back to sync.
+ */
+export declare function maybeSpawnTranscriptHookAfterCompletion(workspacePath: string, effective: Record<string, unknown>): void;

package/dist/core/transcript-completion-hook.js

@@ -0,0 +1,90 @@
+import { existsSync, mkdirSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { spawn } from "node:child_process";
+const LOCK_REL = ".workspace-kit/improvement/transcript-hook.lock";
+const LOCK_STALE_MS = 120_000;
+export function readAfterTaskCompletedHook(effective) {
+    const imp = effective.improvement;
+    if (!imp || typeof imp !== "object" || Array.isArray(imp))
+        return "off";
+    const hooks = imp.hooks;
+    if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+        return "off";
+    const v = hooks.afterTaskCompleted;
+    if (v === "sync" || v === "ingest")
+        return v;
+    return "off";
+}
+export function resolveWorkspaceKitCli(workspacePath) {
+    const candidates = [
+        path.join(workspacePath, "node_modules", "@workflow-cannon", "workspace-kit", "dist", "cli.js"),
+        path.join(workspacePath, "dist", "cli.js")
+    ];
+    for (const c of candidates) {
+        if (existsSync(c))
+            return c;
+    }
+    return null;
+}
+function lockPath(workspacePath) {
+    return path.join(workspacePath, LOCK_REL);
+}
+function hookLockBusy(workspacePath) {
+    const fp = lockPath(workspacePath);
+    try {
+        const st = statSync(fp);
+        return Date.now() - st.mtimeMs < LOCK_STALE_MS;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * After a task reaches `completed`, optionally spawn sync/ingest without blocking the transition (T274).
+ * Ingest requires WORKSPACE_KIT_POLICY_APPROVAL in the parent env or falls back to sync.
+ */
+export function maybeSpawnTranscriptHookAfterCompletion(workspacePath, effective) {
+    const mode = readAfterTaskCompletedHook(effective);
+    if (mode === "off")
+        return;
+    if (hookLockBusy(workspacePath))
+        return;
+    let subcommand = "sync-transcripts";
+    if (mode === "ingest" && process.env.WORKSPACE_KIT_POLICY_APPROVAL?.trim()) {
+        subcommand = "ingest-transcripts";
+    }
+    const cli = resolveWorkspaceKitCli(workspacePath);
+    if (!cli)
+        return;
+    const fp = lockPath(workspacePath);
+    try {
+        mkdirSync(path.dirname(fp), { recursive: true });
+        writeFileSync(fp, `${JSON.stringify({ at: new Date().toISOString(), subcommand })}\n`, "utf8");
+    }
+    catch {
+        return;
+    }
+    const child = spawn(process.execPath, [cli, "run", subcommand, "{}"], {
+        cwd: workspacePath,
+        detached: true,
+        stdio: "ignore",
+        env: process.env
+    });
+    child.unref();
+    child.on("exit", () => {
+        try {
+            unlinkSync(fp);
+        }
+        catch {
+            /* ignore */
+        }
+    });
+    child.on("error", () => {
+        try {
+            unlinkSync(fp);
+        }
+        catch {
+            /* ignore */
+        }
+    });
+}

package/dist/core/workspace-kit-config.js

@@ -13,7 +13,30 @@ export const KIT_CONFIG_DEFAULTS = {
     tasks: {
         storeRelativePath: ".workspace-kit/tasks/state.json"
     },
-    documentation: {}
+    documentation: {},
+    responseTemplates: {
+        enforcementMode: "advisory",
+        defaultTemplateId: "default",
+        commandOverrides: {}
+    },
+    improvement: {
+        transcripts: {
+            sourcePath: ".cursor/agent-transcripts",
+            archivePath: "agent-transcripts",
+            maxFilesPerSync: 5000,
+            maxBytesPerFile: 50_000_000,
+            maxTotalScanBytes: 500_000_000,
+            discoveryPaths: []
+        },
+        cadence: {
+            minIntervalMinutes: 15,
+            skipIfNoNewTranscripts: true,
+            maxRecommendationCandidatesPerRun: 500
+        },
+        hooks: {
+            afterTaskCompleted: "off"
+        }
+    }
 };
 /**
  * Static module-level defaults keyed by module id (merged in registry startup order).
@@ -30,7 +53,24 @@ export const MODULE_CONFIG_CONTRIBUTIONS = {
     },
     approvals: {},
     planning: {},
-    improvement: {}
+    improvement: {
+        transcripts: {
+            sourcePath: ".cursor/agent-transcripts",
+            archivePath: "agent-transcripts",
+            maxFilesPerSync: 5000,
+            maxBytesPerFile: 50_000_000,
+            maxTotalScanBytes: 500_000_000,
+            discoveryPaths: []
+        },
+        cadence: {
+            minIntervalMinutes: 15,
+            skipIfNoNewTranscripts: true,
+            maxRecommendationCandidatesPerRun: 500
+        },
+        hooks: {
+            afterTaskCompleted: "off"
+        }
+    }
 };
 export function deepMerge(target, source) {
     const out = { ...target };