@asermax/tachikoma 2.0.0

package/dist/extensions/workflows/cleanup.js

@@ -0,0 +1,38 @@
+import { deleteScratchpad } from "./tools.js";
+export const DEFAULT_STALE_HOURS = 24;
+/**
+ * Post-processor that expires workflow instances abandoned across sessions:
+ * soft-deletes records untouched for longer than the threshold and removes
+ * their scratchpad files.
+ */
+export const createStaleWorkflowCleanup = (repository, staleHours = DEFAULT_STALE_HOURS) => ({
+    name: "stale-workflow-cleanup",
+    phase: "main",
+    async process({ log }) {
+        let stale;
+        try {
+            stale = repository.listStale(staleHours * 60 * 60 * 1000);
+        }
+        catch (error) {
+            log.error({ err: error }, "failed to list stale workflows");
+            return;
+        }
+        if (stale.length === 0)
+            return;
+        let cleaned = 0;
+        for (const state of stale) {
+            try {
+                if (repository.softDelete(state.id)) {
+                    deleteScratchpad(state.scratchpadPath);
+                    cleaned += 1;
+                }
+            }
+            catch (error) {
+                log.warn({ err: error, workflowId: state.id }, "failed to clean up stale workflow");
+            }
+        }
+        if (cleaned > 0)
+            log.info({ cleaned, staleHours }, "cleaned up stale workflow(s)");
+    },
+});
+//# sourceMappingURL=cleanup.js.map

package/dist/extensions/workflows/cleanup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanup.js","sourceRoot":"","sources":["../../../src/extensions/workflows/cleanup.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAItC;;;;GAIG;AACH,MAAM,CAAC,MAAM,0BAA0B,GAAG,CACxC,UAA2B,EAC3B,aAAqB,mBAAmB,EACzB,EAAE,CAAC,CAAC;IACnB,IAAI,EAAE,wBAAwB;IAC9B,KAAK,EAAE,MAAM;IAEb,KAAK,CAAC,OAAO,CAAC,EAAE,GAAG,EAAE;QACnB,IAAI,KAA+C,CAAC;QAEpD,IAAI,CAAC;YACH,KAAK,GAAG,UAAU,CAAC,SAAS,CAAC,UAAU,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC;QAC5D,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,GAAG,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,EAAE,gCAAgC,CAAC,CAAC;YAC5D,OAAO;QACT,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QAE/B,IAAI,OAAO,GAAG,CAAC,CAAC;QAEhB,KAAK,MAAM,KAAK,IAAI,KAAK,EAAE,CAAC;YAC1B,IAAI,CAAC;gBACH,IAAI,UAAU,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;oBACpC,gBAAgB,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;oBACvC,OAAO,IAAI,CAAC,CAAC;gBACf,CAAC;YACH,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,GAAG,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,EAAE,UAAU,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,mCAAmC,CAAC,CAAC;YACtF,CAAC;QACH,CAAC;QAED,IAAI,OAAO,GAAG,CAAC;YAAE,GAAG,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,UAAU,EAAE,EAAE,8BAA8B,CAAC,CAAC;IACrF,CAAC;CACF,CAAC,CAAC"}

package/dist/extensions/workflows/index.d.ts

@@ -0,0 +1,11 @@
+interface WorkflowsConfig {
+    enabled: boolean;
+    staleHours: number;
+}
+/**
+ * Workflow engine: directory-based workflow definitions inside skills execute as
+ * database-persisted step state machines, driven by the agent through lifecycle
+ * tools. Stale instances are expired at session close.
+ */
+declare const _default: import("../api.ts").TachikomaExtension<WorkflowsConfig>;
+export default _default;

package/dist/extensions/workflows/index.js

@@ -0,0 +1,42 @@
+import { mkdir } from "node:fs/promises";
+import { join } from "node:path";
+import { Type } from "typebox";
+import { defineExtension } from "../api.js";
+import { createStaleWorkflowCleanup, DEFAULT_STALE_HOURS } from "./cleanup.js";
+import { findWorkflow } from "./loader.js";
+import { WorkflowStateRepository } from "./repository.js";
+import { registerWorkflowTools } from "./tools.js";
+/**
+ * Workflow engine: directory-based workflow definitions inside skills execute as
+ * database-persisted step state machines, driven by the agent through lifecycle
+ * tools. Stale instances are expired at session close.
+ */
+export default defineExtension({
+    name: "workflows",
+    configSchema: Type.Object({
+        enabled: Type.Boolean({ default: true }),
+        staleHours: Type.Number({ default: DEFAULT_STALE_HOURS }),
+    }),
+    setup(app) {
+        if (!app.extensionConfig.enabled) {
+            app.log.info("workflows disabled by configuration");
+            return;
+        }
+        const repository = new WorkflowStateRepository(app.db);
+        const skillsDir = app.workspace.resolve("skills");
+        const scratchpadDir = join(app.workspace.dataDir, "scratchpads");
+        app.bootstrap("ensure-scratchpad-dir", async () => {
+            await mkdir(scratchpadDir, { recursive: true });
+        });
+        app.agent.use((pi) => {
+            registerWorkflowTools(pi, {
+                repository,
+                findWorkflow: (skillName, workflowName) => findWorkflow(skillsDir, skillName, workflowName, app.log),
+                scratchpadDir,
+                log: app.log,
+            });
+        });
+        app.sessions.registerProcessor(createStaleWorkflowCleanup(repository, app.extensionConfig.staleHours));
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/extensions/workflows/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/extensions/workflows/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAE/B,OAAO,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,0BAA0B,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAOnD;;;;GAIG;AACH,eAAe,eAAe,CAAkB;IAC9C,IAAI,EAAE,WAAW;IAEjB,YAAY,EAAE,IAAI,CAAC,MAAM,CAAC;QACxB,OAAO,EAAE,IAAI,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;QACxC,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,mBAAmB,EAAE,CAAC;KAC1D,CAAC;IAEF,KAAK,CAAC,GAAG;QACP,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,OAAO,EAAE,CAAC;YACjC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,qCAAqC,CAAC,CAAC;YACpD,OAAO;QACT,CAAC;QAED,MAAM,UAAU,GAAG,IAAI,uBAAuB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACvD,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAClD,MAAM,aAAa,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QAEjE,GAAG,CAAC,SAAS,CAAC,uBAAuB,EAAE,KAAK,IAAI,EAAE;YAChD,MAAM,KAAK,CAAC,aAAa,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC,CAAC,CAAC;QAEH,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE;YACnB,qBAAqB,CAAC,EAAE,EAAE;gBACxB,UAAU;gBACV,YAAY,EAAE,CAAC,SAAS,EAAE,YAAY,EAAE,EAAE,CACxC,YAAY,CAAC,SAAS,EAAE,SAAS,EAAE,YAAY,EAAE,GAAG,CAAC,GAAG,CAAC;gBAC3D,aAAa;gBACb,GAAG,EAAE,GAAG,CAAC,GAAG;aACb,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;QAEH,GAAG,CAAC,QAAQ,CAAC,iBAAiB,CAC5B,0BAA0B,CAAC,UAAU,EAAE,GAAG,CAAC,eAAe,CAAC,UAAU,CAAC,CACvE,CAAC;IACJ,CAAC;CACF,CAAC,CAAC"}

package/dist/extensions/workflows/loader.d.ts

@@ -0,0 +1,27 @@
+import type { Logger } from "../../log.ts";
+export interface StepDefinition {
+    /** Step identifier (matches the directory name). */
+    id: string;
+    title: string;
+    instructionsPath: string;
+    referencesPath: string | null;
+    scriptsPath: string | null;
+    /** When false, the step can be skipped. */
+    required: boolean;
+    /** Extensible frontmatter fields beyond the reserved keys. */
+    properties: Record<string, unknown>;
+}
+export interface WorkflowDefinition {
+    skillName: string;
+    workflowName: string;
+    /** Ordered by step directory name (e.g. 01-plan, 02-execute). */
+    steps: StepDefinition[];
+    path: string;
+}
+/** Load every workflow defined under a skill directory's workflows/ subdirectory. */
+export declare const loadSkillWorkflows: (skillDir: string, skillName: string, log: Logger) => WorkflowDefinition[];
+/**
+ * Resolve a single workflow definition from the skills root, reading the
+ * filesystem fresh on every call so definition edits apply without a restart.
+ */
+export declare const findWorkflow: (skillsRoot: string, skillName: string, workflowName: string, log: Logger) => WorkflowDefinition | null;

package/dist/extensions/workflows/loader.js

@@ -0,0 +1,90 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { parseFrontmatter } from "@earendil-works/pi-coding-agent";
+const RESERVED_STEP_KEYS = ["title", "required", "skippable"];
+const isDirectory = (path) => {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const listDirectories = (path) => {
+    try {
+        return readdirSync(path, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name);
+    }
+    catch {
+        return [];
+    }
+};
+const loadStep = (stepDir, stepId, context, log) => {
+    const instructionsPath = join(stepDir, "instructions.md");
+    if (!existsSync(instructionsPath)) {
+        log.warn({ ...context, step: stepId }, "step missing instructions.md — skipped");
+        return null;
+    }
+    let frontmatter;
+    try {
+        frontmatter = parseFrontmatter(readFileSync(instructionsPath, "utf8")).frontmatter;
+    }
+    catch (error) {
+        log.warn({ err: error, ...context, step: stepId }, "failed to parse instructions.md — skipped");
+        return null;
+    }
+    const title = frontmatter.title;
+    if (typeof title !== "string" || title.length === 0) {
+        log.warn({ ...context, step: stepId }, "step has missing or invalid title — skipped");
+        return null;
+    }
+    let required = true;
+    if ("required" in frontmatter) {
+        if (typeof frontmatter.required !== "boolean") {
+            log.warn({ ...context, step: stepId }, "step has invalid required type — skipped");
+            return null;
+        }
+        required = frontmatter.required;
+    }
+    else if ("skippable" in frontmatter) {
+        // skippable is the deprecated alias for required: false
+        log.warn({ ...context, step: stepId }, "step uses deprecated 'skippable' field; use 'required: false' instead");
+        required = frontmatter.skippable !== true;
+    }
+    const properties = Object.fromEntries(Object.entries(frontmatter).filter(([key]) => !RESERVED_STEP_KEYS.includes(key)));
+    const referencesPath = join(stepDir, "references");
+    const scriptsPath = join(stepDir, "scripts");
+    return {
+        id: stepId,
+        title,
+        instructionsPath,
+        referencesPath: isDirectory(referencesPath) ? referencesPath : null,
+        scriptsPath: isDirectory(scriptsPath) ? scriptsPath : null,
+        required,
+        properties,
+    };
+};
+const loadWorkflow = (workflowDir, skillName, workflowName, log) => {
+    const steps = listDirectories(workflowDir)
+        .sort()
+        .map((stepId) => loadStep(join(workflowDir, stepId), stepId, { skillName, workflowName }, log))
+        .filter((step) => step != null);
+    return { skillName, workflowName, steps, path: workflowDir };
+};
+/** Load every workflow defined under a skill directory's workflows/ subdirectory. */
+export const loadSkillWorkflows = (skillDir, skillName, log) => {
+    const workflowsDir = join(skillDir, "workflows");
+    return listDirectories(workflowsDir).map((workflowName) => loadWorkflow(join(workflowsDir, workflowName), skillName, workflowName, log));
+};
+/**
+ * Resolve a single workflow definition from the skills root, reading the
+ * filesystem fresh on every call so definition edits apply without a restart.
+ */
+export const findWorkflow = (skillsRoot, skillName, workflowName, log) => {
+    const workflowDir = join(skillsRoot, skillName, "workflows", workflowName);
+    if (!isDirectory(workflowDir))
+        return null;
+    return loadWorkflow(workflowDir, skillName, workflowName, log);
+};
+//# sourceMappingURL=loader.js.map

package/dist/extensions/workflows/loader.js.map

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

package/dist/extensions/workflows/model.d.ts

@@ -0,0 +1,19 @@
+export declare const STEP_STATES: {
+    readonly pending: "pending";
+    readonly started: "started";
+    readonly completed: "completed";
+    readonly skipped: "skipped";
+};
+export type StepState = keyof typeof STEP_STATES;
+export type StepStates = Record<string, StepState>;
+/**
+ * Step metadata frozen into the database when a workflow instance starts, so a
+ * running workflow survives definition edits on disk.
+ */
+export interface StepSnapshot {
+    id: string;
+    title: string;
+    required: boolean;
+    /** Step directory; instructions.md is read from here when the step activates. */
+    path: string;
+}

package/dist/extensions/workflows/model.js

@@ -0,0 +1,7 @@
+export const STEP_STATES = {
+    pending: "pending",
+    started: "started",
+    completed: "completed",
+    skipped: "skipped",
+};
+//# sourceMappingURL=model.js.map

package/dist/extensions/workflows/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../../src/extensions/workflows/model.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,SAAS,EAAE,WAAW;IACtB,OAAO,EAAE,SAAS;CACV,CAAC"}

package/dist/extensions/workflows/repository.d.ts

@@ -0,0 +1,24 @@
+import type { AppDatabase } from "../../db/index.ts";
+import type { StepSnapshot, StepStates } from "./model.ts";
+import { type WorkflowStateRecord } from "./schema.ts";
+export interface NewWorkflowState {
+    id: string;
+    skillName: string;
+    workflowName: string;
+    stepStates: StepStates;
+    definitionSnapshot: StepSnapshot[];
+    scratchpadPath: string;
+}
+/** Persistence for workflow instances. All reads exclude soft-deleted records. */
+export declare class WorkflowStateRepository {
+    private readonly db;
+    constructor(db: AppDatabase);
+    create(state: NewWorkflowState): WorkflowStateRecord;
+    get(id: string): WorkflowStateRecord | null;
+    getActive(skillName: string, workflowName: string): WorkflowStateRecord | null;
+    update(id: string, patch: Partial<Pick<WorkflowStateRecord, "currentStep" | "stepStates">>): WorkflowStateRecord | null;
+    softDelete(id: string): boolean;
+    listActive(): WorkflowStateRecord[];
+    /** Active workflows whose last update is older than the threshold. */
+    listStale(thresholdMs: number): WorkflowStateRecord[];
+}

package/dist/extensions/workflows/repository.js

@@ -0,0 +1,61 @@
+import { and, eq, isNull, lt } from "drizzle-orm";
+import { workflowStates } from "./schema.js";
+/** Persistence for workflow instances. All reads exclude soft-deleted records. */
+export class WorkflowStateRepository {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    create(state) {
+        const now = new Date();
+        return this.db
+            .insert(workflowStates)
+            .values({ ...state, currentStep: null, createdAt: now, updatedAt: now })
+            .returning()
+            .get();
+    }
+    get(id) {
+        return (this.db
+            .select()
+            .from(workflowStates)
+            .where(and(eq(workflowStates.id, id), isNull(workflowStates.deletedAt)))
+            .get() ?? null);
+    }
+    getActive(skillName, workflowName) {
+        return (this.db
+            .select()
+            .from(workflowStates)
+            .where(and(eq(workflowStates.skillName, skillName), eq(workflowStates.workflowName, workflowName), isNull(workflowStates.deletedAt)))
+            .get() ?? null);
+    }
+    update(id, patch) {
+        return (this.db
+            .update(workflowStates)
+            .set({ ...patch, updatedAt: new Date() })
+            .where(and(eq(workflowStates.id, id), isNull(workflowStates.deletedAt)))
+            .returning()
+            .get() ?? null);
+    }
+    softDelete(id) {
+        const now = new Date();
+        return (this.db
+            .update(workflowStates)
+            .set({ deletedAt: now, updatedAt: now })
+            .where(and(eq(workflowStates.id, id), isNull(workflowStates.deletedAt)))
+            .returning()
+            .get() != null);
+    }
+    listActive() {
+        return this.db.select().from(workflowStates).where(isNull(workflowStates.deletedAt)).all();
+    }
+    /** Active workflows whose last update is older than the threshold. */
+    listStale(thresholdMs) {
+        const cutoff = new Date(Date.now() - thresholdMs);
+        return this.db
+            .select()
+            .from(workflowStates)
+            .where(and(isNull(workflowStates.deletedAt), lt(workflowStates.updatedAt, cutoff)))
+            .all();
+    }
+}
+//# sourceMappingURL=repository.js.map

package/dist/extensions/workflows/repository.js.map

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

package/dist/extensions/workflows/schema.d.ts

@@ -0,0 +1,193 @@
+import type { StepSnapshot, StepStates } from "./model.ts";
+export declare const workflowStates: import("drizzle-orm/sqlite-core").SQLiteTableWithColumns<{
+    name: "workflow_states";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "id";
+            tableName: "workflow_states";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        skillName: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "skill_name";
+            tableName: "workflow_states";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        workflowName: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "workflow_name";
+            tableName: "workflow_states";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        currentStep: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "current_step";
+            tableName: "workflow_states";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        stepStates: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "step_states";
+            tableName: "workflow_states";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: StepStates;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: StepStates;
+        }>;
+        definitionSnapshot: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "definition_snapshot";
+            tableName: "workflow_states";
+            dataType: "json";
+            columnType: "SQLiteTextJson";
+            data: StepSnapshot[];
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            $type: StepSnapshot[];
+        }>;
+        scratchpadPath: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "scratchpad_path";
+            tableName: "workflow_states";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
+        deletedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "deleted_at";
+            tableName: "workflow_states";
+            dataType: "date";
+            columnType: "SQLiteTimestamp";
+            data: Date;
+            driverParam: number;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "created_at";
+            tableName: "workflow_states";
+            dataType: "date";
+            columnType: "SQLiteTimestamp";
+            data: Date;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        updatedAt: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "updated_at";
+            tableName: "workflow_states";
+            dataType: "date";
+            columnType: "SQLiteTimestamp";
+            data: Date;
+            driverParam: number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: "sqlite";
+}>;
+export type WorkflowStateRecord = typeof workflowStates.$inferSelect;

package/dist/extensions/workflows/schema.js

@@ -0,0 +1,20 @@
+import { index, integer, sqliteTable, text } from "drizzle-orm/sqlite-core";
+export const workflowStates = sqliteTable("workflow_states", {
+    id: text("id").primaryKey(),
+    skillName: text("skill_name").notNull(),
+    workflowName: text("workflow_name").notNull(),
+    currentStep: text("current_step"),
+    stepStates: text("step_states", { mode: "json" }).$type().notNull(),
+    definitionSnapshot: text("definition_snapshot", { mode: "json" })
+        .$type()
+        .notNull(),
+    scratchpadPath: text("scratchpad_path").notNull(),
+    deletedAt: integer("deleted_at", { mode: "timestamp" }),
+    createdAt: integer("created_at", { mode: "timestamp" }).notNull(),
+    updatedAt: integer("updated_at", { mode: "timestamp" }).notNull(),
+}, (table) => [
+    index("ix_workflow_states_skill_name").on(table.skillName),
+    index("ix_workflow_states_workflow_name").on(table.workflowName),
+    index("ix_workflow_states_active_lookup").on(table.skillName, table.workflowName),
+]);
+//# sourceMappingURL=schema.js.map

package/dist/extensions/workflows/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/extensions/workflows/schema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,yBAAyB,CAAC;AAI5E,MAAM,CAAC,MAAM,cAAc,GAAG,WAAW,CACvC,iBAAiB,EACjB;IACE,EAAE,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE;IAC3B,SAAS,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC,OAAO,EAAE;IACvC,YAAY,EAAE,IAAI,CAAC,eAAe,CAAC,CAAC,OAAO,EAAE;IAC7C,WAAW,EAAE,IAAI,CAAC,cAAc,CAAC;IACjC,UAAU,EAAE,IAAI,CAAC,aAAa,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,KAAK,EAAc,CAAC,OAAO,EAAE;IAC/E,kBAAkB,EAAE,IAAI,CAAC,qBAAqB,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;SAC9D,KAAK,EAAkB;SACvB,OAAO,EAAE;IACZ,cAAc,EAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC,OAAO,EAAE;IACjD,SAAS,EAAE,OAAO,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;IACvD,SAAS,EAAE,OAAO,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE;IACjE,SAAS,EAAE,OAAO,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE;CAClE,EACD,CAAC,KAAK,EAAE,EAAE,CAAC;IACT,KAAK,CAAC,+BAA+B,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC;IAC1D,KAAK,CAAC,kCAAkC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,YAAY,CAAC;IAChE,KAAK,CAAC,kCAAkC,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,YAAY,CAAC;CAClF,CACF,CAAC"}

package/dist/extensions/workflows/tools.d.ts

@@ -0,0 +1,27 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import type { Logger } from "../../log.ts";
+import type { WorkflowDefinition } from "./loader.ts";
+import { type StepSnapshot, type StepStates } from "./model.ts";
+import type { WorkflowStateRepository } from "./repository.ts";
+export interface WorkflowToolDeps {
+    repository: WorkflowStateRepository;
+    findWorkflow: (skillName: string, workflowName: string) => WorkflowDefinition | null;
+    scratchpadDir: string;
+    log: Logger;
+}
+export declare const UpdateActionSchema: Type.TUnsafe<"start" | "skip" | "complete">;
+export declare const EndActionSchema: Type.TUnsafe<"abort" | "complete">;
+export type UpdateAction = Static<typeof UpdateActionSchema>;
+export type EndAction = Static<typeof EndActionSchema>;
+export declare const deleteScratchpad: (path: string) => void;
+/**
+ * Validate a step transition against the current states and the frozen definition.
+ * Returns null when valid, an error message otherwise.
+ */
+export declare const validateTransition: (stepStates: StepStates, stepId: string, action: UpdateAction, snapshot: StepSnapshot[]) => string | null;
+export declare const handleStartWorkflow: (deps: WorkflowToolDeps, skillName: string, workflowName: string) => string;
+export declare const handleUpdateWorkflowState: (deps: WorkflowToolDeps, workflowId: string, stepId: string, action: UpdateAction) => string;
+export declare const handleQueryWorkflow: (deps: WorkflowToolDeps, workflowId?: string) => string;
+export declare const handleEndWorkflow: (deps: WorkflowToolDeps, workflowId: string, action: EndAction) => string;
+export declare const registerWorkflowTools: (pi: ExtensionAPI, deps: WorkflowToolDeps) => void;