@workflow-cannon/workspace-kit 0.7.0 → 0.9.0

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,128 @@
+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 EVENT_LOG_REL = ".workspace-kit/improvement/transcript-hook-events.jsonl";
+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;
+    }
+}
+function appendHookEvent(workspacePath, event, details) {
+    const fp = path.join(workspacePath, EVENT_LOG_REL);
+    try {
+        mkdirSync(path.dirname(fp), { recursive: true });
+        writeFileSync(fp, `${JSON.stringify({
+            schemaVersion: 1,
+            timestamp: new Date().toISOString(),
+            event,
+            ...details
+        })}\n`, { encoding: "utf8", flag: "a" });
+    }
+    catch {
+        // Observability must never block task transitions.
+    }
+}
+/**
+ * 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") {
+        appendHookEvent(workspacePath, "skipped", { reason: "hook-mode-off" });
+        return;
+    }
+    if (hookLockBusy(workspacePath)) {
+        appendHookEvent(workspacePath, "skipped", { reason: "lock-busy", mode });
+        return;
+    }
+    let subcommand = "sync-transcripts";
+    if (mode === "ingest" && process.env.WORKSPACE_KIT_POLICY_APPROVAL?.trim()) {
+        subcommand = "ingest-transcripts";
+    }
+    const cli = resolveWorkspaceKitCli(workspacePath);
+    if (!cli) {
+        appendHookEvent(workspacePath, "failed", {
+            reason: "cli-not-found",
+            mode,
+            subcommand
+        });
+        return;
+    }
+    const fp = lockPath(workspacePath);
+    try {
+        mkdirSync(path.dirname(fp), { recursive: true });
+        writeFileSync(fp, `${JSON.stringify({ at: new Date().toISOString(), subcommand })}\n`, "utf8");
+    }
+    catch {
+        appendHookEvent(workspacePath, "failed", {
+            reason: "lock-write-failed",
+            mode,
+            subcommand
+        });
+        return;
+    }
+    appendHookEvent(workspacePath, "started", { mode, subcommand });
+    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 */
+        }
+        appendHookEvent(workspacePath, "completed", { mode, subcommand });
+    });
+    child.on("error", () => {
+        try {
+            unlinkSync(fp);
+        }
+        catch {
+            /* ignore */
+        }
+        appendHookEvent(workspacePath, "failed", {
+            reason: "spawn-error",
+            mode,
+            subcommand
+        });
+    });
+}

package/dist/core/workspace-kit-config.d.ts

@@ -12,7 +12,8 @@ export declare function getProjectConfigPath(workspacePath: string): string;
 export declare const KIT_CONFIG_DEFAULTS: Record<string, unknown>;
 /**
  * Static module-level defaults keyed by module id (merged in registry startup order).
- * Each value is deep-merged into the aggregate before project/env/invocation.
+ * Keep true defaults in KIT_CONFIG_DEFAULTS as the canonical source; use this map
+ * only when a module contributes additional non-default config structure.
  */
 export declare const MODULE_CONFIG_CONTRIBUTIONS: Record<string, Record<string, unknown>>;
 export declare function deepMerge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;

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

@@ -14,42 +14,38 @@ export const KIT_CONFIG_DEFAULTS = {
         storeRelativePath: ".workspace-kit/tasks/state.json"
     },
     documentation: {},
+    responseTemplates: {
+        enforcementMode: "advisory",
+        defaultTemplateId: "default",
+        commandOverrides: {}
+    },
     improvement: {
         transcripts: {
-            sourcePath: ".cursor/agent-transcripts",
-            archivePath: "agent-transcripts"
+            sourcePath: "",
+            archivePath: "agent-transcripts",
+            maxFilesPerSync: 5000,
+            maxBytesPerFile: 50_000_000,
+            maxTotalScanBytes: 500_000_000,
+            discoveryPaths: []
         },
         cadence: {
             minIntervalMinutes: 15,
-            skipIfNoNewTranscripts: true
+            skipIfNoNewTranscripts: true,
+            maxRecommendationCandidatesPerRun: 500
+        },
+        hooks: {
+            afterTaskCompleted: "off"
         }
     }
 };
 /**
  * Static module-level defaults keyed by module id (merged in registry startup order).
- * Each value is deep-merged into the aggregate before project/env/invocation.
+ * Keep true defaults in KIT_CONFIG_DEFAULTS as the canonical source; use this map
+ * only when a module contributes additional non-default config structure.
  */
 export const MODULE_CONFIG_CONTRIBUTIONS = {
-    "task-engine": {
-        tasks: {
-            storeRelativePath: ".workspace-kit/tasks/state.json"
-        }
-    },
-    documentation: {
-        documentation: {}
-    },
     approvals: {},
-    planning: {},
-    improvement: {
-        transcripts: {
-            sourcePath: ".cursor/agent-transcripts",
-            archivePath: "agent-transcripts"
-        },
-        cadence: {
-            minIntervalMinutes: 15,
-            skipIfNoNewTranscripts: true
-        }
-    }
+    planning: {}
 };
 export function deepMerge(target, source) {
     const out = { ...target };

package/dist/modules/approvals/index.js

@@ -1,4 +1,4 @@
-import { resolveActor } from "../../core/policy.js";
+import { resolveActorWithFallback } from "../../core/policy.js";
 import { runReviewItem } from "./review-runtime.js";
 export const approvalsModule = {
     registration: {
@@ -40,7 +40,7 @@ export const approvalsModule = {
         const args = command.args ?? {};
         const actor = typeof args.actor === "string" && args.actor.trim().length > 0
             ? args.actor.trim()
-            : ctx.resolvedActor ?? resolveActor(ctx.workspacePath, args, process.env);
+            : ctx.resolvedActor ?? (await resolveActorWithFallback(ctx.workspacePath, args, process.env));
         const taskId = typeof args.taskId === "string" ? args.taskId : "";
         const decision = args.decision;
         if (decision !== "accept" && decision !== "decline" && decision !== "accept_edited") {