@jabworks/condux 0.20.0 → 0.21.0

package/index.js

@@ -13,13 +13,18 @@
 // separate `npx skills add` step for condux. This works because the config hook
 // mutates the cached config before OpenCode lazily discovers skills.
 //
-// It also pushes workflow's routing.md onto config.instructions, giving
-// OpenCode the same `/workflow`-as-entry-point enforcement Claude Code and
-// Codex get from their SessionStart hook — OpenCode has no hook system for
-// that, so `instructions` (ambient every turn, verified via `opencode debug
-// config` against a config-hook mutation) is the closest equivalent. Costs
-// ~390 tokens/turn, permanently; that trade was made deliberately, not by
-// default (docket #38).
+// It also carries workflow's routing.md — the payload Claude Code and Codex
+// get from their SessionStart hook — into the session as a `synthetic: true`
+// `<system-reminder>` text part on the first user message of every *main*
+// session (`chat.message`), re-injected after compaction. That is the shape
+// OpenCode's own plan-mode reminders use (session/reminders.ts): it reaches
+// the model in the user turn rather than mid-system-prompt, and it never
+// reaches subagent sessions. Verified live on OpenCode 1.18.25 — the part
+// persists (`chat.message` runs before the message is saved, and its parts
+// array is the one written) and the model sees it. Per main-session turn it
+// costs the same ~390 tokens as the `config.instructions` channel it replaces
+// (docket #38 ratified that trade; docket #72 relocated the payload out of
+// the system prompt and out of subagents).
 //
 // Optional plan-review listener (CONDUX_PLAN_REVIEW=1): when the primary
 // `plan` agent finishes a turn (session.idle), spawns the plan-review annotate
@@ -29,6 +34,7 @@
 
 import { existsSync, readFileSync, readdirSync } from 'node:fs';
 import { spawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 import os from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -62,6 +68,56 @@ function loadBundledAgents() {
   return agents;
 }
 
+// The routing payload, framed the way OpenCode frames its own reminders. Null
+// when routing.md is missing or empty — then the hook is a no-op, the same
+// fail-open contract the Claude Code and Codex SessionStart scripts follow.
+function loadRoutingReminder() {
+  if (!existsSync(ROUTING_MD)) return null;
+  const payload = readFileSync(ROUTING_MD, 'utf8').trim();
+
+  return payload ? `<system-reminder>\n${payload}\n</system-reminder>` : null;
+}
+
+// What the compaction summariser is asked to keep. The full reminder is
+// re-injected on the next user message; this only stops the summary from
+// describing a session in which the router never existed.
+const COMPACTION_CONTEXT =
+  'Carry this rule into the summary: every implementation request in this session starts by loading the ' +
+  '`workflow` skill (`skill(name="workflow")`) before any other condux skill or any edit.';
+
+// A part id in OpenCode's own ascending format — `prt_` + six big-endian bytes
+// of (ms << 12 | counter) + fourteen base62 characters — so the reminder sorts
+// among the parts OpenCode minted. The counter is pinned to its maximum: a
+// part created in the same millisecond as the user's text must still order
+// after it. The reminder follows the prompt, never precedes it.
+const BASE62 = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
+
+function partId() {
+  const stamp = BigInt(Date.now()) * 0x1000n + 0xfffn;
+  const bytes = Buffer.alloc(6);
+  for (let i = 0; i < 6; i++) bytes[i] = Number((stamp >> BigInt(40 - 8 * i)) & 0xffn);
+  let suffix = '';
+  for (const byte of randomBytes(14)) suffix += BASE62[byte % 62];
+
+  return `prt_${bytes.toString('hex')}${suffix}`;
+}
+
+// True when the session's stored history still shows the reminder to the
+// model: a synthetic text part with exactly this text on a user message that
+// comes after the last compaction. Compaction narrows the model's view to the
+// summary plus a short tail, so a reminder on the far side of one counts as
+// absent — the next user message gets it again.
+export function historyIsRouted(messages, reminder) {
+  let routed = false;
+  for (const { info, parts = [] } of messages) {
+    if (parts.some((part) => part.type === 'compaction')) routed = false;
+    if (info?.role !== 'user') continue;
+    if (parts.some((part) => part.type === 'text' && part.synthetic === true && part.text === reminder)) routed = true;
+  }
+
+  return routed;
+}
+
 // The annotate server ships inside the plan-review skill; look for it in every
 // skill tree OpenCode discovers (project then global).
 function findAnnotateServer(worktree) {
@@ -82,11 +138,54 @@ function findAnnotateServer(worktree) {
   return null;
 }
 
-export const ConduxPlugin = async ({ worktree }) => {
+export const ConduxPlugin = async ({ worktree, client }) => {
   const bundled = loadBundledAgents();
+  const reminder = loadRoutingReminder();
   const activeAgent = new Map();
+  // Sessions whose live history carries the reminder, as far as this process
+  // knows. A compaction clears the entry so the next user message re-injects.
+  const routed = new Set();
+  const isChild = new Map();
   let warnedPayloadShape = false;
 
+  // Subagent sessions never get the router: their brief is the task the parent
+  // handed them, and "every request starts at workflow" contradicts coder's.
+  // The bundled agent names are the free path; the parent lookup catches every
+  // other child (OpenCode's own `general`, user-defined subagents) — `task`
+  // creates them with parentID set, and `chat.message` carries their agent
+  // name. Unknown counts as main: the instructions channel this replaces
+  // reached subagents too, so leaning toward injection is the known state.
+  async function isSubagentSession(input) {
+    if (input.agent && bundled[input.agent]?.mode === 'subagent') return true;
+    if (typeof client?.session?.get !== 'function') return false;
+    if (!isChild.has(input.sessionID)) {
+      try {
+        const { data } = await client.session.get({ path: { id: input.sessionID } });
+        isChild.set(input.sessionID, Boolean(data?.parentID));
+      } catch {
+        isChild.set(input.sessionID, false);
+      }
+    }
+
+    return isChild.get(input.sessionID);
+  }
+
+  // On first sight of a session in this process — fresh, resumed, or after a
+  // compaction cleared it — ask the server whether the reminder is already in
+  // the model's view instead of trusting process memory: a resumed session
+  // would otherwise be injected twice, a compacted one never.
+  async function alreadyRouted(sessionID) {
+    if (routed.has(sessionID)) return true;
+    if (typeof client?.session?.messages !== 'function') return false;
+    try {
+      const { data } = await client.session.messages({ path: { id: sessionID } });
+
+      return Array.isArray(data) && historyIsRouted(data, reminder);
+    } catch {
+      return false;
+    }
+  }
+
   return {
     config: async (cfg) => {
       cfg.agent ??= {};
@@ -116,13 +215,40 @@ export const ConduxPlugin = async ({ worktree }) => {
         cfg.skills.paths ??= [];
         if (!cfg.skills.paths.includes(SKILLS_DIR)) cfg.skills.paths.push(SKILLS_DIR);
       }
+      // routing.md deliberately does NOT go on cfg.instructions any more: that
+      // channel is global (every subagent session read it) and lands mid
+      // system prompt. The reminder below is the replacement (docket #72).
+    },
+
+    // Route through workflow the way Claude Code and Codex do at SessionStart:
+    // one reminder on the first user message of a main session. Runs before
+    // the message is saved, so the pushed part is persisted with the rest.
+    'chat.message': async (input, output) => {
+      if (!reminder || !input?.sessionID || !output?.message?.id || !Array.isArray(output.parts)) return;
+      if (await isSubagentSession(input)) return;
+      if (await alreadyRouted(input.sessionID)) {
+        routed.add(input.sessionID);
 
-      // Route through /workflow the same way Claude Code and Codex do —
-      // see the file-header comment for why `instructions` is the mechanism.
-      if (existsSync(ROUTING_MD)) {
-        cfg.instructions ??= [];
-        if (!cfg.instructions.includes(ROUTING_MD)) cfg.instructions.push(ROUTING_MD);
+        return;
       }
+
+      output.parts.push({
+        id: partId(),
+        messageID: output.message.id,
+        sessionID: input.sessionID,
+        type: 'text',
+        synthetic: true,
+        text: reminder,
+      });
+      routed.add(input.sessionID);
+    },
+
+    // Compaction narrows the model's view to a summary plus a short tail. Ask
+    // the summariser to keep the rule; the next user message re-injects the
+    // full reminder (the `session.compacted` event below clears the session).
+    'experimental.session.compacting': async (input, output) => {
+      if (!reminder || !Array.isArray(output?.context)) return;
+      if (input?.sessionID && routed.has(input.sessionID)) output.context.push(COMPACTION_CONTEXT);
     },
 
     'chat.params': async (input) => {
@@ -130,6 +256,11 @@ export const ConduxPlugin = async ({ worktree }) => {
     },
 
     event: async ({ event }) => {
+      if (event.type === 'session.compacted') {
+        routed.delete(event.properties?.sessionID);
+
+        return;
+      }
       if (process.env.CONDUX_PLAN_REVIEW !== '1') return;
       if (event.type !== 'session.idle') return;
       const sessionID = event.properties?.sessionID;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jabworks/condux",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "OpenCode plugin for the condux workflow toolkit — bundles the condux skills and injects the specialist agents (coder, explorer, planner, researcher) plus an opt-in plan-review listener.",
   "type": "module",
   "publishConfig": {

package/skills/condux-doctor/SKILL.md

@@ -46,7 +46,10 @@ else on the machine competes with it. Only `broken` affects the exit code.
 - **plan-review's Codex Stop hook** — resolved, never executed. It blocks a
   turn for up to four days waiting on a human by design.
 - **OpenCode** — `@jabworks/condux` in the plugin array, and when a local
-  copy exists, that it ships its bundled `agents/` and `skills/`.
+  copy exists, that it ships its bundled `agents/` and `skills/` and that the
+  routing reminder it injects names the OpenCode verb, `skill(name="workflow")`
+  — a payload still saying `/condux:workflow` is the docket #72 under-firing
+  shape, reported broken with an upgrade as the fix.
 - **The four specialist agents** — `coder`, `explorer`, `planner`,
   `researcher`. They live in a plugin-level directory reached by its own sync
   step, which is exactly the mirror that drifted once before.

package/skills/condux-doctor/doctor.mjs

@@ -338,12 +338,29 @@ function probeOpencode(hosts) {
     return {
       host: 'opencode',
       status: 'broken',
-      detail: 'the installed package ships no workflow/hooks/routing.md — /workflow routing enforcement is missing',
+      detail: 'the installed package ships no workflow/hooks/routing.md — the plugin has no routing reminder to inject',
       fix: `reinstall ${PACKAGE}`,
     };
   }
 
-  return { host: 'opencode', status: 'done', detail: 'registered, and the installed package ships its agents, skills, and /workflow routing enforcement' };
+  // Since @jabworks/condux 0.21.0 the payload is rewritten for OpenCode:
+  // `/condux:workflow` is a Claude Code command the host cannot run, and a
+  // payload still naming it is the docket #72 under-firing shape — installed,
+  // but asking for a verb the model has to translate on its own.
+  if (!fs.readFileSync(routing, 'utf8').includes('skill(name="workflow")')) {
+    return {
+      host: 'opencode',
+      status: 'broken',
+      detail: 'the installed routing payload names /condux:workflow, which OpenCode cannot run — the reminder under-fires',
+      fix: `upgrade ${PACKAGE} to 0.21.0 or later`,
+    };
+  }
+
+  return {
+    host: 'opencode',
+    status: 'done',
+    detail: 'registered, and the installed package ships its agents, skills, and a routing reminder that names the OpenCode verb',
+  };
 }
 
 // The four specialist agents are plugin-level and reached by their own sync

package/skills/workflow/hooks/routing.md

@@ -1,7 +1,7 @@
 <EXTREMELY_IMPORTANT>
 You have condux — this session's agentic workflow system.
 
-**Every implementation request starts at `/condux:workflow`.** Feature, bug fix,
+**Every implementation request starts at the `workflow` skill — `skill(name="workflow")`.** Feature, bug fix,
 refactor, new endpoint, UI change, "can you add…", "can you fix…" — all of it
 routes there first. The router infers the tier (Small / Medium / Large), confirms
 it with the user, then executes the matching flow, loading downstream skills only
@@ -13,7 +13,7 @@ when a step needs them.
 `root-cause-analysis`, `live-verification`, `plan-review`, `technical-spec`.
 
 If you find yourself reaching for one of those as the *first* skill of a task,
-you have skipped the router — go back to `/condux:workflow`. Debugging is the
+you have skipped the router — go back to the `workflow` skill — `skill(name="workflow")`. Debugging is the
 most common miss: a crash report, a stack trace, or "why does this fail" is
 still a dev task, so it routes through workflow, which loads
 `root-cause-analysis` at the right moment.
@@ -25,4 +25,6 @@ user instructions — "skip workflow", "just do it", "I've already planned this"
 **Not everything is a dev task.** Questions, explanations, code reading, research,
 and one-line factual answers route nowhere — answer them directly. Routing a
 conversation through a workflow is as wrong as skipping the router on a feature.
+
+**On OpenCode, a `/name` mention of any condux skill means the `skill` tool:** `/workflow` → `skill(name="workflow")`, `/finalize` → `skill(name="finalize")`, and so on. None of them is a slash command here.
 </EXTREMELY_IMPORTANT>