@nt-ai-lab/deterministic-agent-workflow-opencode 0.1.0

package/dist/features/opencode-plugin/entrypoint/opencode-workflow-plugin.d.ts

@@ -0,0 +1,10 @@
+import type { Hooks } from '@opencode-ai/plugin';
+import type { BaseWorkflowState, RehydratableWorkflow } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import type { IdleEventHookDeps, OpenCodePlugin, OpenCodeWorkflowPluginConfig } from '../../../platform/domain/opencode-workflow-plugin-types';
+export declare const IDLE_RECOVERY_MESSAGE = "You have stopped. You should never stop until the workflow is complete unless your current state permits stopping.";
+type OpenCodeEventHook = NonNullable<Hooks['event']>;
+/** @riviere-role cli-entrypoint */
+export declare function createSessionIdleEventHook(deps: IdleEventHookDeps): OpenCodeEventHook;
+/** @riviere-role cli-entrypoint */
+export declare function createOpenCodeWorkflowPlugin<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string = string, TOperation extends string = string>(config: OpenCodeWorkflowPluginConfig<TWorkflow, TState, TDeps, TStateName, TOperation>): OpenCodePlugin;
+export {};

package/dist/features/opencode-plugin/entrypoint/opencode-workflow-plugin.js

@@ -0,0 +1,242 @@
+import { appendFileSync, readFileSync, readdirSync, } from 'node:fs';
+import { basename, extname, join, } from 'node:path';
+import { homedir } from 'node:os';
+import { tool } from '@opencode-ai/plugin/tool';
+import { WorkflowEngine } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import { createPreToolUseHandler, createWorkflowRunner, getRepositoryName, } from '@nt-ai-lab/deterministic-agent-workflow-cli';
+import { createStore } from '@nt-ai-lab/deterministic-agent-workflow-event-store';
+import { OpenCodeTranscriptReader } from '../../../platform/infra/external-clients/opencode/opencode-transcript-reader.js';
+export const IDLE_RECOVERY_MESSAGE = 'You have stopped. You should never stop until the workflow is complete unless your current state permits stopping.';
+const TRANSLATION_NOTE = [
+    '> **OpenCode**: When instructions say `/dev-workflow-v2:workflow <op> [args]`, call',
+    '> the `workflow` tool instead: `operation: "<op>"`, `args: ["<arg>", ...]`.',
+    '> Example: `/dev-workflow-v2:workflow transition REVIEWING`',
+    '>   → `workflow({ operation: "transition", args: ["REVIEWING"] })`',
+    '',
+    '---',
+    '',
+    '',
+].join('\n');
+function injectTranslationNote(content) {
+    return `${TRANSLATION_NOTE}${content}`;
+}
+function isSessionPromptClient(value) {
+    return typeof value === 'object' && value !== null && 'session' in value;
+}
+async function promptIdleRecovery(client, sessionID) {
+    await client.session.promptAsync({
+        path: { id: sessionID },
+        body: {
+            parts: [{
+                    type: 'text',
+                    text: IDLE_RECOVERY_MESSAGE,
+                }],
+        },
+    });
+}
+/** @riviere-role cli-entrypoint */
+export function createSessionIdleEventHook(deps) {
+    return async ({ event }) => {
+        if (event.type !== 'session.idle') {
+            return;
+        }
+        if (!deps.hasSessionStarted(event.properties.sessionID)) {
+            return;
+        }
+        await deps.sendIdleRecoveryPrompt(event.properties.sessionID);
+    };
+}
+/** @riviere-role cli-entrypoint */
+export function createOpenCodeWorkflowPlugin(config) {
+    const store = createStore(resolveWorkflowEventsDatabasePath());
+    const dbPath = resolveOpenCodeDatabasePath(config.databasePath);
+    function buildEngineContext(sessionID) {
+        const transcriptReader = new OpenCodeTranscriptReader(sessionID);
+        const now = () => new Date().toISOString();
+        const rawReadFile = (path) => readFileSync(path, 'utf8');
+        const readFile = config.routes === undefined
+            ? rawReadFile
+            : (path) => injectTranslationNote(rawReadFile(path));
+        const engineDeps = {
+            store,
+            getPluginRoot: () => config.pluginRoot,
+            getEnvFilePath: () => join(homedir(), '.opencode', 'opencode.env'),
+            getRepositoryName: () => getRepositoryName(process.cwd()),
+            readFile,
+            appendToFile: (path, content) => appendFileSync(path, content),
+            now,
+            transcriptReader,
+        };
+        const platformCtx = {
+            getPluginRoot: () => config.pluginRoot,
+            now,
+            getSessionId: () => sessionID,
+            store,
+        };
+        return {
+            engineDeps,
+            workflowDeps: config.buildWorkflowDeps(platformCtx),
+        };
+    }
+    return async (input) => {
+        const handler = config.customGates === undefined
+            ? createPreToolUseHandler({
+                bashForbidden: config.bashForbidden,
+                isWriteAllowed: config.isWriteAllowed,
+            })
+            : createPreToolUseHandler({
+                bashForbidden: config.bashForbidden,
+                isWriteAllowed: config.isWriteAllowed,
+                customGates: config.customGates,
+            });
+        const eventHook = createSessionIdleEventHook({
+            hasSessionStarted: (sessionID) => {
+                const { engineDeps, workflowDeps } = buildEngineContext(sessionID);
+                const engine = new WorkflowEngine(config.workflowDefinition, engineDeps, workflowDeps);
+                return engine.hasSessionStarted(sessionID);
+            },
+            sendIdleRecoveryPrompt: async (sessionID) => {
+                if (input !== undefined && isSessionPromptClient(input.client)) {
+                    await promptIdleRecovery(input.client, sessionID);
+                }
+            },
+        });
+        const toolExecuteBefore = async (hookInput, output) => {
+            const { engineDeps, workflowDeps } = buildEngineContext(hookInput.sessionID);
+            const engine = new WorkflowEngine(config.workflowDefinition, engineDeps, workflowDeps);
+            if (config.routes === undefined) {
+                if (engine.hasSession(hookInput.sessionID)) {
+                    // Session already exists for the default non-router path.
+                }
+                else {
+                    engine.startSession(hookInput.sessionID, dbPath);
+                }
+            }
+            else if (engine.hasSessionStarted(hookInput.sessionID)) {
+                // Routed mode only enforces tools after the session starts.
+            }
+            else {
+                return;
+            }
+            const result = handler(engine, hookInput.sessionID, hookInput.tool, output.args);
+            if (result.type === 'blocked') {
+                throw new TypeError(result.output);
+            }
+        };
+        if (config.routes === undefined) {
+            return {
+                event: eventHook,
+                'tool.execute.before': toolExecuteBefore,
+            };
+        }
+        const routes = config.routes;
+        const workflowTool = tool({
+            description: 'Execute a workflow operation (init, transition, record-*)',
+            args: {
+                operation: tool.schema.string().describe('operation name, e.g. "init", "transition", "record-issue"'),
+                args: tool.schema.array(tool.schema.string()).optional().describe('operation arguments'),
+            },
+            execute: async (rawArgs, ctx) => {
+                const operation = rawArgs.operation;
+                const argList = rawArgs.args ?? [];
+                const { engineDeps, workflowDeps } = buildEngineContext(ctx.sessionID);
+                const runner = config.customGates === undefined
+                    ? createWorkflowRunner({
+                        workflowDefinition: config.workflowDefinition,
+                        routes,
+                        bashForbidden: config.bashForbidden,
+                        isWriteAllowed: config.isWriteAllowed,
+                    })
+                    : createWorkflowRunner({
+                        workflowDefinition: config.workflowDefinition,
+                        routes,
+                        bashForbidden: config.bashForbidden,
+                        isWriteAllowed: config.isWriteAllowed,
+                        customGates: config.customGates,
+                    });
+                return runner([operation, ...argList], engineDeps, workflowDeps, {
+                    getSessionId: () => ctx.sessionID,
+                    getSessionTranscriptPath: () => dbPath,
+                    getSessionRepository: () => getRepositoryName(ctx.worktree),
+                }).output;
+            },
+        });
+        const commands = loadCommands(resolveCommandDirectories(config.commandDirectories), resolveCommandPrefix(config.commandPrefix));
+        return {
+            event: eventHook,
+            'tool.execute.before': toolExecuteBefore,
+            tool: { workflow: workflowTool },
+            ...(Object.keys(commands).length > 0
+                ? {
+                    config: async (openCodeConfig) => {
+                        registerCommands(openCodeConfig, commands);
+                    },
+                }
+                : {}),
+        };
+    };
+}
+function loadCommands(commandDirectories, commandPrefix) {
+    const commands = {};
+    for (const dir of commandDirectories) {
+        const files = readCommandFiles(dir);
+        if (files === undefined) {
+            continue;
+        }
+        for (const file of files) {
+            if (!file.endsWith('.md'))
+                continue;
+            const baseName = basename(file, extname(file));
+            const name = `${commandPrefix}${baseName}`;
+            if (Object.hasOwn(commands, name))
+                continue;
+            const filePath = join(dir, file);
+            const content = readFileSync(filePath, 'utf8');
+            commands[name] = {
+                description: `Workflow command: ${name}`,
+                template: injectTranslationNote(content),
+            };
+        }
+    }
+    return commands;
+}
+function registerCommands(config, commands) {
+    config.command ??= {};
+    for (const [name, command] of Object.entries(commands)) {
+        if (Object.hasOwn(config.command, name)) {
+            continue;
+        }
+        config.command[name] = command;
+    }
+}
+function readCommandFiles(directory) {
+    try {
+        return readdirSync(directory);
+    }
+    catch {
+        return undefined;
+    }
+}
+function resolveCommandDirectories(directories) {
+    if (directories === undefined) {
+        return [];
+    }
+    return directories;
+}
+function resolveCommandPrefix(prefix) {
+    if (prefix === undefined) {
+        return '';
+    }
+    return prefix;
+}
+function resolveOpenCodeDatabasePath(configured) {
+    if (configured !== undefined)
+        return configured;
+    return process.env['OPENCODE_DB'] ?? join(homedir(), '.local', 'share', 'opencode', 'opencode.db');
+}
+function resolveWorkflowEventsDatabasePath() {
+    const configured = process.env['WORKFLOW_EVENTS_DB'];
+    if (configured !== undefined && configured !== '')
+        return configured;
+    return join(homedir(), '.workflow-events.db');
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createOpenCodeWorkflowPlugin, createSessionIdleEventHook, } from './features/opencode-plugin/entrypoint/opencode-workflow-plugin';
+export type { IdleEventHookDeps, OpenCodePlugin, OpenCodeWorkflowPluginConfig, } from './platform/domain/opencode-workflow-plugin-types';
+export { OpenCodeTranscriptReader } from './platform/infra/external-clients/opencode/opencode-transcript-reader';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createOpenCodeWorkflowPlugin, createSessionIdleEventHook, } from './features/opencode-plugin/entrypoint/opencode-workflow-plugin.js';
+export { OpenCodeTranscriptReader } from './platform/infra/external-clients/opencode/opencode-transcript-reader.js';

package/dist/platform/domain/opencode-workflow-plugin-types.d.ts

@@ -0,0 +1,23 @@
+import type { BaseWorkflowState, RehydratableWorkflow, WorkflowDefinition } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+import type { PlatformContext, PreToolUseHandlerConfig, RouteMap } from '@nt-ai-lab/deterministic-agent-workflow-cli';
+import type { Hooks, Plugin } from '@opencode-ai/plugin';
+type OpenCodePluginInput = Parameters<Plugin>[0];
+type OpenCodePluginOptions = Parameters<Plugin>[1];
+/** @riviere-role value-object */
+export type IdleEventHookDeps = {
+    readonly hasSessionStarted: (sessionID: string) => boolean;
+    readonly sendIdleRecoveryPrompt: (sessionID: string) => Promise<void>;
+};
+/** @riviere-role value-object */
+export type OpenCodePlugin = (input?: OpenCodePluginInput, options?: OpenCodePluginOptions) => Promise<Hooks>;
+/** @riviere-role value-object */
+export type OpenCodeWorkflowPluginConfig<TWorkflow extends RehydratableWorkflow<TState>, TState extends BaseWorkflowState<TStateName>, TDeps, TStateName extends string = string, TOperation extends string = string> = PreToolUseHandlerConfig<TWorkflow, TState, TStateName> & {
+    readonly workflowDefinition: WorkflowDefinition<TWorkflow, TState, TDeps, TStateName, TOperation>;
+    readonly buildWorkflowDeps: (platform: PlatformContext) => TDeps;
+    readonly pluginRoot: string;
+    readonly databasePath?: string;
+    readonly routes?: RouteMap<TWorkflow, TState>;
+    readonly commandDirectories?: readonly string[];
+    readonly commandPrefix?: string;
+};
+export {};

package/dist/platform/domain/opencode-workflow-plugin-types.js

@@ -0,0 +1 @@
+export {};

package/dist/platform/infra/external-clients/opencode/opencode-transcript-reader.d.ts

@@ -0,0 +1,9 @@
+import type { TranscriptMessage, TranscriptReader } from '@nt-ai-lab/deterministic-agent-workflow-engine';
+/** @riviere-role external-client-model */
+export declare class OpenCodeTranscriptReader implements TranscriptReader {
+    private readonly sessionId;
+    constructor(sessionId: string);
+    readMessages(dbPath: string): readonly TranscriptMessage[];
+    private queryMessages;
+    private parseRow;
+}

package/dist/platform/infra/external-clients/opencode/opencode-transcript-reader.js

@@ -0,0 +1,63 @@
+import { openSqliteDatabase, } from '@nt-ai-lab/deterministic-agent-workflow-event-store';
+import { z } from 'zod';
+const textPartSchema = z.object({
+    type: z.literal('text'),
+    text: z.string()
+});
+const messageDataSchema = z.object({ parts: z.array(z.unknown()) });
+const messageRowSchema = z.object({
+    id: z.string(),
+    data: z.string(),
+});
+/** @riviere-role external-client-model */
+export class OpenCodeTranscriptReader {
+    sessionId;
+    constructor(sessionId) {
+        this.sessionId = sessionId;
+    }
+    readMessages(dbPath) {
+        try {
+            const db = openSqliteDatabase(dbPath, { readonly: true });
+            try {
+                return this.queryMessages(db);
+            }
+            finally {
+                db.close();
+            }
+        }
+        catch {
+            return [];
+        }
+    }
+    queryMessages(db) {
+        return db
+            .prepare(`SELECT id, data FROM message
+         WHERE session_id = ? AND json_extract(data, '$.role') = 'assistant'
+         ORDER BY time_created ASC`)
+            .all(this.sessionId)
+            .flatMap((row) => this.parseRow(row));
+    }
+    parseRow(row) {
+        const rowResult = messageRowSchema.safeParse(row);
+        if (!rowResult.success) {
+            return [];
+        }
+        const parsedData = JSON.parse(rowResult.data.data);
+        const dataResult = messageDataSchema.safeParse(parsedData);
+        if (!dataResult.success) {
+            return [];
+        }
+        return [{
+                id: rowResult.data.id,
+                textContent: extractFirstText(dataResult.data.parts),
+            }];
+    }
+}
+function extractFirstText(parts) {
+    for (const part of parts) {
+        const result = textPartSchema.safeParse(part);
+        if (result.success)
+            return result.data.text;
+    }
+    return undefined;
+}

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@nt-ai-lab/deterministic-agent-workflow-opencode",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@nt-ai-lab/deterministic-agent-workflow-cli": "workspace:*",
+    "@nt-ai-lab/deterministic-agent-workflow-engine": "workspace:*",
+    "@nt-ai-lab/deterministic-agent-workflow-event-store": "workspace:*",
+    "@opencode-ai/plugin": "^1.4.3",
+    "zod": "^3.25.76"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}