@workflow-cannon/workspace-kit 0.18.0 → 0.24.0

package/dist/modules/agent-behavior/persistence.d.ts

@@ -0,0 +1,6 @@
+import type { ModuleLifecycleContext } from "../../contracts/module-contract.js";
+import type { BehaviorWorkspaceStateV1 } from "./types.js";
+export declare function behaviorPersistenceMode(effectiveConfig: Record<string, unknown> | undefined): "json" | "sqlite";
+export declare function behaviorSqliteRelativePath(effectiveConfig: Record<string, unknown> | undefined): string;
+export declare function loadBehaviorWorkspaceState(ctx: ModuleLifecycleContext): Promise<BehaviorWorkspaceStateV1>;
+export declare function saveBehaviorWorkspaceState(ctx: ModuleLifecycleContext, state: BehaviorWorkspaceStateV1): Promise<void>;

package/dist/modules/agent-behavior/persistence.js

@@ -0,0 +1,89 @@
+import fs from "node:fs";
+import path from "node:path";
+import { UnifiedStateDb } from "../../core/state/unified-state-db.js";
+const MODULE_ID = "agent-behavior";
+const STATE_SCHEMA = 1;
+const JSON_REL = path.join(".workspace-kit", "agent-behavior", "state.json");
+export function behaviorPersistenceMode(effectiveConfig) {
+    const tasks = effectiveConfig?.tasks;
+    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
+        return "json";
+    }
+    const b = tasks.persistenceBackend;
+    return b === "sqlite" ? "sqlite" : "json";
+}
+export function behaviorSqliteRelativePath(effectiveConfig) {
+    const tasks = effectiveConfig?.tasks;
+    if (!tasks || typeof tasks !== "object" || Array.isArray(tasks)) {
+        return ".workspace-kit/tasks/workspace-kit.db";
+    }
+    const p = tasks.sqliteDatabaseRelativePath;
+    return typeof p === "string" && p.trim().length > 0
+        ? p.trim()
+        : ".workspace-kit/tasks/workspace-kit.db";
+}
+function jsonPath(workspacePath) {
+    return path.join(workspacePath, JSON_REL);
+}
+function emptyState() {
+    return { schemaVersion: 1, activeProfileId: null, customProfiles: {} };
+}
+function parseState(raw) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return emptyState();
+    }
+    const o = raw;
+    if (o.schemaVersion !== 1) {
+        return emptyState();
+    }
+    const custom = o.customProfiles;
+    const customProfiles = {};
+    if (custom && typeof custom === "object" && !Array.isArray(custom)) {
+        for (const [k, v] of Object.entries(custom)) {
+            if (typeof k === "string" && k.startsWith("custom:")) {
+                customProfiles[k] = v;
+            }
+        }
+    }
+    const active = typeof o.activeProfileId === "string" && o.activeProfileId.length > 0
+        ? o.activeProfileId
+        : null;
+    return { schemaVersion: 1, activeProfileId: active, customProfiles };
+}
+export async function loadBehaviorWorkspaceState(ctx) {
+    const cfg = ctx.effectiveConfig;
+    if (behaviorPersistenceMode(cfg) === "sqlite") {
+        const rel = behaviorSqliteRelativePath(cfg);
+        const db = new UnifiedStateDb(ctx.workspacePath, rel);
+        const row = db.getModuleState(MODULE_ID);
+        if (!row?.state) {
+            return emptyState();
+        }
+        return parseState(row.state);
+    }
+    const fp = jsonPath(ctx.workspacePath);
+    try {
+        const raw = JSON.parse(await fs.promises.readFile(fp, "utf8"));
+        return parseState(raw);
+    }
+    catch {
+        return emptyState();
+    }
+}
+export async function saveBehaviorWorkspaceState(ctx, state) {
+    const cfg = ctx.effectiveConfig;
+    const body = {
+        schemaVersion: 1,
+        activeProfileId: state.activeProfileId,
+        customProfiles: { ...state.customProfiles }
+    };
+    if (behaviorPersistenceMode(cfg) === "sqlite") {
+        const rel = behaviorSqliteRelativePath(cfg);
+        const db = new UnifiedStateDb(ctx.workspacePath, rel);
+        db.setModuleState(MODULE_ID, STATE_SCHEMA, body);
+        return;
+    }
+    const fp = jsonPath(ctx.workspacePath);
+    await fs.promises.mkdir(path.dirname(fp), { recursive: true });
+    await fs.promises.writeFile(fp, `${JSON.stringify(body, null, 2)}\n`, "utf8");
+}

package/dist/modules/agent-behavior/store.d.ts

@@ -0,0 +1,34 @@
+import type { BehaviorProfile, BehaviorWorkspaceStateV1, BehaviorProvenanceEntry } from "./types.js";
+export declare class BehaviorProfileStore {
+    private state;
+    constructor(initial: BehaviorWorkspaceStateV1);
+    getState(): BehaviorWorkspaceStateV1;
+    listIds(): {
+        id: string;
+        label: string;
+        kind: "builtin" | "custom";
+    }[];
+    getRawProfile(id: string): BehaviorProfile | null;
+    /** Resolve `extends` chain; returns null if missing or cycle (cycle truncated). */
+    resolveProfile(id: string, stack?: Set<string>): BehaviorProfile | null;
+    getActiveProfileId(): string | null;
+    setActiveProfileId(id: string | null): void;
+    putCustomProfile(profile: BehaviorProfile): void;
+    deleteCustomProfile(id: string): void;
+    resolveEffectiveWithProvenance(): {
+        effective: BehaviorProfile;
+        provenance: BehaviorProvenanceEntry[];
+    };
+}
+export declare function materializeCustomFromBase(baseId: string, store: BehaviorProfileStore, newId: string, overrides: {
+    label?: string;
+    summary?: string;
+    dimensions?: Partial<BehaviorProfile["dimensions"]>;
+    interactionNotes?: string;
+}): {
+    ok: true;
+    profile: BehaviorProfile;
+} | {
+    ok: false;
+    message: string;
+};

package/dist/modules/agent-behavior/store.js

@@ -0,0 +1,119 @@
+import { BUILTIN_PROFILES, DEFAULT_BUILTIN_PROFILE_ID } from "./builtins.js";
+import { mergeDimensions, validateBehaviorProfile } from "./validate.js";
+export class BehaviorProfileStore {
+    state;
+    constructor(initial) {
+        this.state = initial;
+    }
+    getState() {
+        return this.state;
+    }
+    listIds() {
+        const out = [];
+        for (const [id, p] of Object.entries(BUILTIN_PROFILES)) {
+            out.push({ id, label: p.label, kind: "builtin" });
+        }
+        for (const [id, p] of Object.entries(this.state.customProfiles)) {
+            out.push({ id, label: p.label, kind: "custom" });
+        }
+        return out.sort((a, b) => a.id.localeCompare(b.id));
+    }
+    getRawProfile(id) {
+        if (BUILTIN_PROFILES[id]) {
+            return { ...BUILTIN_PROFILES[id], dimensions: { ...BUILTIN_PROFILES[id].dimensions } };
+        }
+        const c = this.state.customProfiles[id];
+        if (!c)
+            return null;
+        return {
+            ...c,
+            dimensions: { ...c.dimensions },
+            metadata: c.metadata ? { ...c.metadata } : undefined
+        };
+    }
+    /** Resolve `extends` chain; returns null if missing or cycle (cycle truncated). */
+    resolveProfile(id, stack = new Set()) {
+        if (stack.has(id)) {
+            return null;
+        }
+        stack.add(id);
+        const raw = this.getRawProfile(id);
+        if (!raw) {
+            stack.delete(id);
+            return null;
+        }
+        if (!raw.extends) {
+            stack.delete(id);
+            return raw;
+        }
+        const base = this.resolveProfile(raw.extends, stack);
+        stack.delete(id);
+        if (!base) {
+            return raw;
+        }
+        return {
+            ...base,
+            ...raw,
+            id: raw.id,
+            label: raw.label,
+            summary: raw.summary,
+            dimensions: mergeDimensions(base.dimensions, raw.dimensions),
+            interactionNotes: raw.interactionNotes ?? base.interactionNotes,
+            extends: raw.extends,
+            metadata: raw.metadata ?? base.metadata
+        };
+    }
+    getActiveProfileId() {
+        return this.state.activeProfileId;
+    }
+    setActiveProfileId(id) {
+        this.state.activeProfileId = id;
+    }
+    putCustomProfile(profile) {
+        this.state.customProfiles[profile.id] = profile;
+    }
+    deleteCustomProfile(id) {
+        delete this.state.customProfiles[id];
+    }
+    resolveEffectiveWithProvenance() {
+        const provenance = [
+            { source: "default", profileId: DEFAULT_BUILTIN_PROFILE_ID }
+        ];
+        let chosen = DEFAULT_BUILTIN_PROFILE_ID;
+        const active = this.state.activeProfileId;
+        if (active) {
+            const resolved = this.resolveProfile(active);
+            if (resolved) {
+                chosen = active;
+                provenance.push({ source: "active", profileId: active });
+                return { effective: resolved, provenance };
+            }
+            provenance.push({ source: "fallback", profileId: DEFAULT_BUILTIN_PROFILE_ID });
+        }
+        const fallback = this.resolveProfile(DEFAULT_BUILTIN_PROFILE_ID);
+        return {
+            effective: fallback ?? BUILTIN_PROFILES[DEFAULT_BUILTIN_PROFILE_ID],
+            provenance
+        };
+    }
+}
+export function materializeCustomFromBase(baseId, store, newId, overrides) {
+    const baseResolved = store.resolveProfile(baseId);
+    if (!baseResolved) {
+        return { ok: false, message: `Base profile '${baseId}' not found` };
+    }
+    const label = overrides.label?.trim() || `${baseResolved.label} (custom)`;
+    const summary = overrides.summary?.trim() || baseResolved.summary;
+    const dimensions = mergeDimensions(baseResolved.dimensions, overrides.dimensions);
+    const draft = {
+        schemaVersion: 1,
+        id: newId,
+        extends: baseId,
+        label,
+        summary,
+        dimensions,
+        interactionNotes: overrides.interactionNotes?.trim(),
+        metadata: { source: "fork", createdAt: new Date().toISOString(), baseProfileId: baseId }
+    };
+    return validateBehaviorProfile(draft);
+}

package/dist/modules/agent-behavior/types.d.ts

@@ -0,0 +1,28 @@
+export declare const BEHAVIOR_PROFILE_SCHEMA_VERSION: 1;
+export type BehaviorDimensions = {
+    deliberationDepth: "low" | "medium" | "high";
+    changeAppetite: "conservative" | "balanced" | "bold";
+    checkInFrequency: "rare" | "normal" | "often";
+    explanationVerbosity: "terse" | "normal" | "verbose";
+    explorationStyle: "linear" | "parallel";
+    ambiguityHandling: "decide" | "ask";
+};
+export type BehaviorProfile = {
+    schemaVersion: typeof BEHAVIOR_PROFILE_SCHEMA_VERSION;
+    id: string;
+    extends?: string;
+    label: string;
+    summary: string;
+    dimensions: BehaviorDimensions;
+    interactionNotes?: string;
+    metadata?: Record<string, unknown>;
+};
+export type BehaviorWorkspaceStateV1 = {
+    schemaVersion: 1;
+    activeProfileId: string | null;
+    customProfiles: Record<string, BehaviorProfile>;
+};
+export type BehaviorProvenanceEntry = {
+    source: "default" | "active" | "fallback";
+    profileId: string;
+};

package/dist/modules/agent-behavior/types.js

@@ -0,0 +1 @@
+export const BEHAVIOR_PROFILE_SCHEMA_VERSION = 1;

package/dist/modules/agent-behavior/validate.d.ts

@@ -0,0 +1,11 @@
+import { type BehaviorDimensions, type BehaviorProfile } from "./types.js";
+export declare function validateBehaviorProfile(raw: unknown, options?: {
+    allowBuiltinId?: boolean;
+}): {
+    ok: true;
+    profile: BehaviorProfile;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function mergeDimensions(base: BehaviorDimensions, patch: Partial<BehaviorDimensions> | undefined): BehaviorDimensions;

package/dist/modules/agent-behavior/validate.js

@@ -0,0 +1,123 @@
+import { BEHAVIOR_PROFILE_SCHEMA_VERSION } from "./types.js";
+const ID_RE = /^(builtin|custom):[a-z0-9-]+$/;
+const FORBIDDEN_NOTE_SNIPPETS = [
+    "ignore policy",
+    "bypass policy",
+    "skip approval",
+    "no approval",
+    "without approval",
+    "chat-only approval",
+    "override principles",
+    "skip tests",
+    "delete production",
+    "exfiltrate"
+];
+const DIMENSION_KEYS = [
+    "deliberationDepth",
+    "changeAppetite",
+    "checkInFrequency",
+    "explanationVerbosity",
+    "explorationStyle",
+    "ambiguityHandling"
+];
+const ENUMS = {
+    deliberationDepth: new Set(["low", "medium", "high"]),
+    changeAppetite: new Set(["conservative", "balanced", "bold"]),
+    checkInFrequency: new Set(["rare", "normal", "often"]),
+    explanationVerbosity: new Set(["terse", "normal", "verbose"]),
+    explorationStyle: new Set(["linear", "parallel"]),
+    ambiguityHandling: new Set(["decide", "ask"])
+};
+export function validateBehaviorProfile(raw, options = {}) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, message: "Profile must be a non-array object" };
+    }
+    const o = raw;
+    if (o.schemaVersion !== BEHAVIOR_PROFILE_SCHEMA_VERSION) {
+        return { ok: false, message: `schemaVersion must be ${BEHAVIOR_PROFILE_SCHEMA_VERSION}` };
+    }
+    const id = typeof o.id === "string" ? o.id.trim() : "";
+    if (!ID_RE.test(id)) {
+        return { ok: false, message: "id must match builtin:<slug> or custom:<slug> (slug: a-z0-9-)" };
+    }
+    if (id.startsWith("builtin:") && !options.allowBuiltinId) {
+        return { ok: false, message: "Cannot use builtin id for custom profile persistence" };
+    }
+    if (!id.startsWith("custom:") && !id.startsWith("builtin:")) {
+        return { ok: false, message: "Invalid id namespace" };
+    }
+    const label = typeof o.label === "string" ? o.label.trim() : "";
+    const summary = typeof o.summary === "string" ? o.summary.trim() : "";
+    if (!label || label.length > 120) {
+        return { ok: false, message: "label required, max 120 chars" };
+    }
+    if (!summary || summary.length > 500) {
+        return { ok: false, message: "summary required, max 500 chars" };
+    }
+    const dimsIn = o.dimensions;
+    if (!dimsIn || typeof dimsIn !== "object" || Array.isArray(dimsIn)) {
+        return { ok: false, message: "dimensions object required" };
+    }
+    const drec = dimsIn;
+    const dimensions = {};
+    for (const key of DIMENSION_KEYS) {
+        const v = drec[key];
+        if (typeof v !== "string" || !ENUMS[key].has(v)) {
+            return { ok: false, message: `dimensions.${key} has invalid value` };
+        }
+        dimensions[key] = v;
+    }
+    let interactionNotes;
+    if (o.interactionNotes !== undefined) {
+        if (typeof o.interactionNotes !== "string") {
+            return { ok: false, message: "interactionNotes must be a string" };
+        }
+        interactionNotes = o.interactionNotes.trim();
+        if (interactionNotes.length > 2000) {
+            return { ok: false, message: "interactionNotes max 2000 chars" };
+        }
+        const lower = interactionNotes.toLowerCase();
+        for (const bad of FORBIDDEN_NOTE_SNIPPETS) {
+            if (lower.includes(bad)) {
+                return {
+                    ok: false,
+                    message: `interactionNotes must not suggest policy or approval bypass (matched: ${bad})`
+                };
+            }
+        }
+    }
+    const profile = {
+        schemaVersion: BEHAVIOR_PROFILE_SCHEMA_VERSION,
+        id,
+        label,
+        summary,
+        dimensions: dimensions,
+        interactionNotes,
+        metadata: typeof o.metadata === "object" && o.metadata !== null && !Array.isArray(o.metadata)
+            ? o.metadata
+            : undefined
+    };
+    if (typeof o.extends === "string" && o.extends.trim().length > 0) {
+        const ex = o.extends.trim();
+        if (!ID_RE.test(ex)) {
+            return { ok: false, message: "extends must be a valid profile id" };
+        }
+        profile.extends = ex;
+    }
+    return { ok: true, profile };
+}
+export function mergeDimensions(base, patch) {
+    if (!patch)
+        return { ...base };
+    const out = { ...base };
+    for (const key of DIMENSION_KEYS) {
+        if (patch[key] !== undefined) {
+            const v = patch[key];
+            if (!ENUMS[key].has(v)) {
+                throw new Error(`Invalid dimension ${key}`);
+            }
+            out[key] = v;
+        }
+    }
+    return out;
+}

package/dist/modules/approvals/index.js

@@ -5,19 +5,16 @@ export const approvalsModule = {
         id: "approvals",
         version: "0.5.0",
         contractVersion: "1",
+        stateSchema: 1,
         capabilities: ["approvals"],
         dependsOn: ["task-engine"],
+        optionalPeers: [],
         enabledByDefault: true,
         config: {
             path: "src/modules/approvals/config.md",
             format: "md",
             description: "Approvals module policy and queue configuration contract."
         },
-        state: {
-            path: "src/modules/approvals/state.md",
-            format: "md",
-            description: "Approvals module decision and queue state contract."
-        },
         instructions: {
             directory: "src/modules/approvals/instructions",
             entries: [
@@ -30,57 +27,63 @@ export const approvalsModule = {
         }
     },
     async onCommand(command, ctx) {
-        if (command.name !== "review-item") {
+        const handlers = {
+            "review-item": async () => {
+                const args = command.args ?? {};
+                const actor = typeof args.actor === "string" && args.actor.trim().length > 0
+                    ? args.actor.trim()
+                    : 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") {
+                    return {
+                        ok: false,
+                        code: "invalid-args",
+                        message: "decision must be accept, decline, or accept_edited"
+                    };
+                }
+                const editedSummary = typeof args.editedSummary === "string" ? args.editedSummary : undefined;
+                let policyTraceRef;
+                const ptr = args.policyTraceRef;
+                if (ptr && typeof ptr === "object" && !Array.isArray(ptr)) {
+                    const o = ptr;
+                    if (typeof o.operationId === "string" && typeof o.timestamp === "string") {
+                        policyTraceRef = { operationId: o.operationId, timestamp: o.timestamp };
+                    }
+                }
+                let configMutationRef;
+                const cmr = args.configMutationRef;
+                if (cmr && typeof cmr === "object" && !Array.isArray(cmr)) {
+                    const o = cmr;
+                    if (typeof o.timestamp === "string" && typeof o.key === "string") {
+                        configMutationRef = { timestamp: o.timestamp, key: o.key };
+                    }
+                }
+                const result = await runReviewItem(ctx, {
+                    taskId,
+                    decision,
+                    editedSummary,
+                    policyTraceRef,
+                    configMutationRef
+                }, actor);
+                return {
+                    ok: result.ok,
+                    code: result.code,
+                    message: result.message,
+                    data: "idempotent" in result && result.idempotent
+                        ? { idempotent: true }
+                        : undefined
+                };
+            }
+        };
+        const handler = handlers[command.name];
+        if (!handler) {
             return {
                 ok: false,
                 code: "unsupported-command",
                 message: `Approvals module does not support '${command.name}'`
             };
         }
-        const args = command.args ?? {};
-        const actor = typeof args.actor === "string" && args.actor.trim().length > 0
-            ? args.actor.trim()
-            : 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") {
-            return {
-                ok: false,
-                code: "invalid-args",
-                message: "decision must be accept, decline, or accept_edited"
-            };
-        }
-        const editedSummary = typeof args.editedSummary === "string" ? args.editedSummary : undefined;
-        let policyTraceRef;
-        const ptr = args.policyTraceRef;
-        if (ptr && typeof ptr === "object" && !Array.isArray(ptr)) {
-            const o = ptr;
-            if (typeof o.operationId === "string" && typeof o.timestamp === "string") {
-                policyTraceRef = { operationId: o.operationId, timestamp: o.timestamp };
-            }
-        }
-        let configMutationRef;
-        const cmr = args.configMutationRef;
-        if (cmr && typeof cmr === "object" && !Array.isArray(cmr)) {
-            const o = cmr;
-            if (typeof o.timestamp === "string" && typeof o.key === "string") {
-                configMutationRef = { timestamp: o.timestamp, key: o.key };
-            }
-        }
-        const result = await runReviewItem(ctx, {
-            taskId,
-            decision,
-            editedSummary,
-            policyTraceRef,
-            configMutationRef
-        }, actor);
-        return {
-            ok: result.ok,
-            code: result.code,
-            message: result.message,
-            data: "idempotent" in result && result.idempotent
-                ? { idempotent: true }
-                : undefined
-        };
+        return handler();
     }
 };

package/dist/modules/approvals/policy-sensitive-commands.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Policy-gated `workspace-kit run` commands owned by the approvals module.
+ */
+export declare const APPROVALS_POLICY_COMMAND_NAMES: readonly [readonly ["review-item", "approvals.review-item"]];

package/dist/modules/approvals/policy-sensitive-commands.js

@@ -0,0 +1,4 @@
+/**
+ * Policy-gated `workspace-kit run` commands owned by the approvals module.
+ */
+export const APPROVALS_POLICY_COMMAND_NAMES = [["review-item", "approvals.review-item"]];

package/dist/modules/approvals/review-runtime.js

@@ -1,6 +1,5 @@
 import { appendLineageEvent } from "../../core/lineage-store.js";
-import { openPlanningStores } from "../task-engine/planning-open.js";
-import { TransitionService } from "../task-engine/service.js";
+import { openPlanningStores, TransitionService } from "../../core/planning/index.js";
 import { appendDecisionRecord, computeDecisionFingerprint, readDecisionFingerprints } from "./decisions-store.js";
 function getEvidenceKey(task) {
     const m = task.metadata;