@dezycro-ai/agent-plugin 2.0.0 → 2.1.0

package/README.md

@@ -116,7 +116,7 @@ See **[PERSONAS.md](./PERSONAS.md)** for the full schema, all supported auth typ
 
 For installation issues, MCP setup, updates, and uninstall instructions, see the [installation guide](https://docs.dezycro.ai/claude-code/install/).
 
-For everything else, sign in at [app.dezycro.ai](https://app.dezycro.ai) and use the in-app support channel.
+For everything else, email [support@dezycro.io](mailto:support@dezycro.io).
 
 ---
 

package/dist/hooks/lib/command-bus.d.ts

@@ -0,0 +1,53 @@
+/**
+ * command-bus.ts — pulls the Agent Command Bus inbox on hook boundaries and renders
+ * unseen events for the agent transcript.
+ *
+ * Polling model (per the Agent Command Bus TRD):
+ * * `session-start` always polls (no floor).
+ * * `user-prompt-submit`, `stop`, `post-tool-use` poll only if `minPollIntervalSeconds`
+ *   has elapsed since the last successful poll.
+ * * On 2xx: advance cursor + lastPollTs, dedup by `eventId` (recent ring, cap 200),
+ *   return new events for surfacing.
+ * * On non-2xx / network failure: cursor stays put, consecutiveFailures++.
+ *
+ * Auth: a bearer token from `.dezycro/companion-token.local.json` (`{"token": "dzy_…"}`)
+ * is sent on every request. Separate from the MCP server token (the user maintains both).
+ *
+ * URL: `<environments[default].apiUrl>/api/v1/workspaces/<wsId>/features/<fId>/inbox`.
+ * Active feature comes from `.dezycro/active-feature.json` written by `/dezycro:work`.
+ */
+import type { CommandBusConfig, CommandBusHook, CommandBusReactionMode, CompanionState, InboxEvent, StatePatch } from '../types';
+export interface PollResult {
+    events: InboxEvent[];
+    statePatch: StatePatch | null;
+    reactionMode: CommandBusReactionMode;
+}
+interface ResolvedConfig {
+    enabled: boolean;
+    hooks: ReadonlySet<CommandBusHook>;
+    minPollIntervalSeconds: number;
+    reactionMode: CommandBusReactionMode;
+}
+/**
+ * Entry point called from each hook handler. Returns the events that should be surfaced
+ * to the agent on this hook fire, plus a state patch the caller must apply.
+ *
+ * Never throws — failures are logged and result in `{events: [], statePatch: null}`.
+ */
+export declare function pollIfDue(repoRoot: string, hookEvent: CommandBusHook, config: CommandBusConfig | undefined, state: CompanionState): Promise<PollResult>;
+/**
+ * Render zero or more events as a chat-ready Markdown block. Returns the empty string
+ * when there is nothing to surface — callers can guard with the return value's length.
+ */
+export declare function renderForAgent(events: InboxEvent[], reactionMode: CommandBusReactionMode): string;
+declare function renderEvent(e: InboxEvent): string;
+declare function reactionGuidance(mode: CommandBusReactionMode): string;
+declare function resolveConfig(c: CommandBusConfig | undefined): ResolvedConfig;
+declare function trimRecent(ids: string[]): string[];
+export declare const _internals: {
+    resolveConfig: typeof resolveConfig;
+    renderEvent: typeof renderEvent;
+    reactionGuidance: typeof reactionGuidance;
+    trimRecent: typeof trimRecent;
+};
+export {};

package/dist/hooks/lib/command-bus.js

@@ -0,0 +1,307 @@
+/**
+ * command-bus.ts — pulls the Agent Command Bus inbox on hook boundaries and renders
+ * unseen events for the agent transcript.
+ *
+ * Polling model (per the Agent Command Bus TRD):
+ * * `session-start` always polls (no floor).
+ * * `user-prompt-submit`, `stop`, `post-tool-use` poll only if `minPollIntervalSeconds`
+ *   has elapsed since the last successful poll.
+ * * On 2xx: advance cursor + lastPollTs, dedup by `eventId` (recent ring, cap 200),
+ *   return new events for surfacing.
+ * * On non-2xx / network failure: cursor stays put, consecutiveFailures++.
+ *
+ * Auth: a bearer token from `.dezycro/companion-token.local.json` (`{"token": "dzy_…"}`)
+ * is sent on every request. Separate from the MCP server token (the user maintains both).
+ *
+ * URL: `<environments[default].apiUrl>/api/v1/workspaces/<wsId>/features/<fId>/inbox`.
+ * Active feature comes from `.dezycro/active-feature.json` written by `/dezycro:work`.
+ */
+'use strict';
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports._internals = void 0;
+exports.pollIfDue = pollIfDue;
+exports.renderForAgent = renderForAgent;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const logging = __importStar(require("./logging"));
+const DEFAULT_HOOKS = [
+    'sessionStart',
+    'userPromptSubmit',
+    'stop',
+    'postToolUse',
+];
+const DEFAULT_MIN_POLL_INTERVAL_SECONDS = 60;
+const DEFAULT_REACTION_MODE = 'HALT_AND_REPLAN';
+const RECENT_EVENT_IDS_CAP = 200;
+const POLL_LIMIT = 100;
+/**
+ * Entry point called from each hook handler. Returns the events that should be surfaced
+ * to the agent on this hook fire, plus a state patch the caller must apply.
+ *
+ * Never throws — failures are logged and result in `{events: [], statePatch: null}`.
+ */
+async function pollIfDue(repoRoot, hookEvent, config, state) {
+    const resolved = resolveConfig(config);
+    const reactionMode = resolved.reactionMode;
+    const empty = { events: [], statePatch: null, reactionMode };
+    if (!resolved.enabled)
+        return empty;
+    if (!resolved.hooks.has(hookEvent) && hookEvent !== 'sessionStart')
+        return empty;
+    // SessionStart always polls regardless of the configured hook set — bootstrap-on-start
+    // is non-negotiable for cursor recovery after compaction.
+    const cbState = state.commandBus;
+    if (hookEvent !== 'sessionStart' && cbState.lastPollTs) {
+        const lastMs = Date.parse(cbState.lastPollTs);
+        if (!Number.isNaN(lastMs)) {
+            const ageSeconds = (Date.now() - lastMs) / 1000;
+            if (ageSeconds < resolved.minPollIntervalSeconds)
+                return empty;
+        }
+    }
+    const feature = readActiveFeature(repoRoot);
+    if (!feature)
+        return empty;
+    const apiUrl = readApiUrl(repoRoot);
+    if (!apiUrl)
+        return empty;
+    const token = readToken(repoRoot);
+    if (!token) {
+        logging.info(repoRoot, 'command_bus_skip_no_token', { hookEvent });
+        return empty;
+    }
+    const since = hookEvent === 'sessionStart' ? null : cbState.cursor;
+    try {
+        const fetched = await fetchInbox(apiUrl, feature, token, since);
+        const seen = new Set(cbState.recentEventIds ?? []);
+        const fresh = fetched.events.filter((e) => !seen.has(e.eventId));
+        const newRing = trimRecent([...(cbState.recentEventIds ?? []), ...fresh.map((e) => e.eventId)]);
+        const patch = {
+            commandBus: {
+                cursor: fetched.nextCursor || cbState.cursor,
+                lastPollTs: fetched.serverTs,
+                consecutiveFailures: 0,
+                recentEventIds: newRing,
+            },
+        };
+        if (fresh.length > 0) {
+            logging.info(repoRoot, 'command_bus_events_received', {
+                hookEvent,
+                count: fresh.length,
+                types: fresh.map((e) => e.eventType),
+            });
+        }
+        return { events: fresh, statePatch: patch, reactionMode };
+    }
+    catch (e) {
+        const patch = {
+            commandBus: {
+                ...cbState,
+                consecutiveFailures: (cbState.consecutiveFailures ?? 0) + 1,
+            },
+        };
+        logging.info(repoRoot, 'command_bus_poll_failed', {
+            hookEvent,
+            error: e instanceof Error ? e.message : String(e),
+            consecutiveFailures: patch.commandBus.consecutiveFailures,
+        });
+        return { events: [], statePatch: patch, reactionMode };
+    }
+}
+/**
+ * Render zero or more events as a chat-ready Markdown block. Returns the empty string
+ * when there is nothing to surface — callers can guard with the return value's length.
+ */
+function renderForAgent(events, reactionMode) {
+    if (events.length === 0)
+        return '';
+    const lines = [];
+    lines.push(`⚠️ Dezycro Command Bus: ${events.length} new event(s) on this feature.`);
+    lines.push('');
+    for (const e of events) {
+        lines.push(renderEvent(e));
+    }
+    if (events.some((e) => e.urgency === 'BLOCKING')) {
+        lines.push('');
+        lines.push(reactionGuidance(reactionMode));
+    }
+    return lines.join('\n');
+}
+function renderEvent(e) {
+    if (e.eventType === 'INVALIDATION') {
+        const summary = stringField(e.payload, 'artifactSummary') ?? '(no summary)';
+        const reason = stringField(e.payload, 'reason') ?? '(no reason)';
+        const prev = stringField(e.payload, 'previousStatus') ?? '?';
+        const sourceLabel = `${e.sourceType.toLowerCase()} ${e.sourceId ?? '?'}`;
+        return `- INVALIDATION (${e.urgency}): ${sourceLabel} ("${truncate(summary, 120)}") — reason: "${truncate(reason, 200)}" — was ${prev}.`;
+    }
+    return `- ${e.eventType} (${e.urgency}) source=${e.sourceType}/${e.sourceId ?? '-'}.`;
+}
+function reactionGuidance(mode) {
+    switch (mode) {
+        case 'HALT_AND_REPLAN':
+            return 'Reaction mode: HALT_AND_REPLAN — pause your current line of work, acknowledge in chat, and re-plan around these invalidations before touching code again.';
+        case 'ACKNOWLEDGE_AND_CONTINUE':
+            return 'Reaction mode: ACKNOWLEDGE_AND_CONTINUE — surface this in your reply but continue current work; do not silently reuse invalidated artifacts.';
+        case 'SILENT_LOG':
+            return 'Reaction mode: SILENT_LOG — recorded for the session transcript; no chat interruption.';
+        default:
+            return '';
+    }
+}
+/* ─── Helpers ─────────────────────────────────────────────────────────── */
+function resolveConfig(c) {
+    const enabled = c?.enabled !== false; // default true
+    const hooks = new Set(c?.pollHooks ?? DEFAULT_HOOKS);
+    hooks.add('sessionStart'); // bootstrap is non-removable
+    const minPollIntervalSeconds = Math.max(0, c?.minPollIntervalSeconds ?? DEFAULT_MIN_POLL_INTERVAL_SECONDS);
+    const reactionMode = c?.reactionMode ?? DEFAULT_REACTION_MODE;
+    return { enabled, hooks, minPollIntervalSeconds, reactionMode };
+}
+function readActiveFeature(repoRoot) {
+    try {
+        const p = path.join(repoRoot, '.dezycro', 'active-feature.json');
+        if (!fs.existsSync(p))
+            return null;
+        const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+        const featureId = typeof raw.featureId === 'string' ? raw.featureId : null;
+        const workspaceId = typeof raw.workspaceId === 'string' ? raw.workspaceId : null;
+        if (!featureId)
+            return null;
+        if (workspaceId)
+            return { workspaceId, featureId };
+        // Older active-feature.json shapes only carry featureId; fall back to config.
+        const wsFromConfig = readWorkspaceId(repoRoot);
+        if (!wsFromConfig)
+            return null;
+        return { workspaceId: wsFromConfig, featureId };
+    }
+    catch {
+        return null;
+    }
+}
+function readApiUrl(repoRoot) {
+    const cfg = readDezycroConfig(repoRoot);
+    if (!cfg)
+        return null;
+    const environments = Array.isArray(cfg.environments) ? cfg.environments : [];
+    const defaultEnv = environments.find((e) => e && e.default === true) ?? environments[0];
+    if (!defaultEnv)
+        return null;
+    const apiUrl = defaultEnv.apiUrl;
+    return typeof apiUrl === 'string' && apiUrl.length > 0 ? apiUrl.replace(/\/$/, '') : null;
+}
+function readWorkspaceId(repoRoot) {
+    const cfg = readDezycroConfig(repoRoot);
+    if (!cfg)
+        return null;
+    const wsId = cfg.workspaceId;
+    return typeof wsId === 'string' ? wsId : null;
+}
+function readDezycroConfig(repoRoot) {
+    try {
+        const p = path.join(repoRoot, '.dezycro', 'config.json');
+        if (!fs.existsSync(p))
+            return null;
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function readToken(repoRoot) {
+    try {
+        const p = path.join(repoRoot, '.dezycro', 'companion-token.local.json');
+        if (!fs.existsSync(p))
+            return null;
+        const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+        const token = raw.token;
+        return typeof token === 'string' && token.length > 0 ? token : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function fetchInbox(apiUrl, feature, token, since) {
+    const url = new URL(`${apiUrl}/api/v1/workspaces/${feature.workspaceId}/features/${feature.featureId}/inbox`);
+    if (since)
+        url.searchParams.set('since', since);
+    url.searchParams.set('limit', String(POLL_LIMIT));
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 5000);
+    try {
+        const res = await fetch(url.toString(), {
+            method: 'GET',
+            headers: {
+                Authorization: `Bearer ${token}`,
+                Accept: 'application/json',
+            },
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            throw new Error(`inbox poll returned ${res.status}`);
+        }
+        const body = (await res.json());
+        if (!body || typeof body.serverTs !== 'string' || typeof body.nextCursor !== 'string') {
+            throw new Error('inbox poll response missing serverTs/nextCursor');
+        }
+        return {
+            serverTs: body.serverTs,
+            nextCursor: body.nextCursor,
+            events: Array.isArray(body.events) ? body.events : [],
+        };
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+function trimRecent(ids) {
+    return ids.length <= RECENT_EVENT_IDS_CAP ? ids : ids.slice(ids.length - RECENT_EVENT_IDS_CAP);
+}
+function stringField(payload, key) {
+    const v = payload?.[key];
+    return typeof v === 'string' ? v : null;
+}
+function truncate(s, max) {
+    return s.length <= max ? s : s.slice(0, max - 1) + '…';
+}
+/* Exported for tests. */
+exports._internals = {
+    resolveConfig,
+    renderEvent,
+    reactionGuidance,
+    trimRecent,
+};

package/dist/hooks/lib/router.d.ts

@@ -11,11 +11,11 @@ import type { PostToolUsePayload, PreToolUsePayload, RouterInvocation, StopPaylo
 export declare const QUALITY_GATE_REASON_PREFIX = "TRD quality gate (deterministic layer) blocked APPROVED transition: ";
 export declare function dispatch(invocation: RouterInvocation): Promise<number>;
 declare function handleUpdateTaskGate(payload: PreToolUsePayload): number;
-declare function handlePostEdit(payload: PostToolUsePayload): number;
+declare function handlePostEdit(payload: PostToolUsePayload): Promise<number>;
 declare function extractEditedPaths(toolInput: Record<string, unknown> | null | undefined): string[];
-declare function handleSessionStart(_payload: SessionStartPayload): number;
-declare function handleUserPromptSubmit(payload: UserPromptSubmitPayload): number;
-declare function handleStop(payload: StopPayload): number;
+declare function handleSessionStart(_payload: SessionStartPayload): Promise<number>;
+declare function handleUserPromptSubmit(payload: UserPromptSubmitPayload): Promise<number>;
+declare function handleStop(payload: StopPayload): Promise<number>;
 declare function transcriptCharsSinceLastStop(payload: StopPayload): number | null;
 declare function readActiveFeatureId(repoRoot: string): string | null;
 declare function handleWorkbookMutation(payload: PostToolUsePayload): number;

package/dist/hooks/lib/router.js

@@ -57,6 +57,7 @@ const hashing = __importStar(require("./hashing"));
 const workbook = __importStar(require("./workbook"));
 const undo = __importStar(require("./undo"));
 const coverage = __importStar(require("./coverage"));
+const commandBus = __importStar(require("./command-bus"));
 const DONE_STATUSES = new Set(['DONE', 'PUSHED']);
 const WRAP_PHRASES = [
     '/dezycro:sync',
@@ -239,10 +240,31 @@ function handleChangeDocumentStatus(payload) {
     return 0;
 }
 /* ─── Pillars 1+2 — post-edit pulse + controller-match (TRD §5.1+§5.2) ─── */
-function handlePostEdit(payload) {
+async function handlePostEdit(payload) {
     const repoRoot = config.findRepoRoot(process.cwd());
     if (!repoRoot)
         return 0;
+    // Autonomous-loop poll for the Agent Command Bus inbox (TRD §Pillar 1 PostToolUse).
+    // Subject to the floor, so most edits no-op. When events arrive, surface them as
+    // additionalContext and short-circuit — pulse/spec-publish logic skips this turn.
+    {
+        const cfg = safeLoadConfig(repoRoot);
+        const cur = state.read(repoRoot);
+        const result = await commandBus.pollIfDue(repoRoot, 'postToolUse', cfg?.companion?.commandBus, cur);
+        if (result.statePatch)
+            state.patch(repoRoot, result.statePatch);
+        const block = commandBus.renderForAgent(result.events, result.reactionMode);
+        if (block) {
+            const out = {
+                hookSpecificOutput: {
+                    hookEventName: 'PostToolUse',
+                    additionalContext: block,
+                },
+            };
+            process.stdout.write(JSON.stringify(out));
+            return 0;
+        }
+    }
     const toolInput = (payload && payload.tool_input) || {};
     const editedPaths = extractEditedPaths(toolInput);
     if (editedPaths.length === 0)
@@ -406,7 +428,7 @@ function handleAuthoringState(flags) {
 }
 /* ─── Pillar 3 — Proactive Workbook Updates (TRD §5.3) ────────────────────── */
 const TRIVIAL_TURN_CHAR_DEFAULT = 600;
-function handleSessionStart(_payload) {
+async function handleSessionStart(_payload) {
     const repoRoot = config.findRepoRoot(process.cwd());
     if (!repoRoot)
         return 0;
@@ -418,9 +440,16 @@ function handleSessionStart(_payload) {
         coverageFetchPending: false,
     });
     logging.info(repoRoot, 'session_start', {});
+    // Bootstrap-on-start poll for the Agent Command Bus inbox. Bypasses the floor.
+    // Failures swallowed; fetched events surface on the next UserPromptSubmit.
+    const cfg = safeLoadConfig(repoRoot);
+    const current = state.read(repoRoot);
+    const result = await commandBus.pollIfDue(repoRoot, 'sessionStart', cfg?.companion?.commandBus, current);
+    if (result.statePatch)
+        state.patch(repoRoot, result.statePatch);
     return 0;
 }
-function handleUserPromptSubmit(payload) {
+async function handleUserPromptSubmit(payload) {
     const repoRoot = config.findRepoRoot(process.cwd());
     if (!repoRoot)
         return 0;
@@ -430,6 +459,27 @@ function handleUserPromptSubmit(payload) {
         currentTurnId: nextTurnId,
         turnAutoLogCount: 0,
     });
+    // Pre-reasoning poll for the Agent Command Bus inbox. If new events arrived
+    // since the last poll, surface them as additionalContext so the agent factors
+    // them in before responding. Wins over the existing undo / coverage paths
+    // for this turn — invalidations are blocking by nature.
+    {
+        const cfg = safeLoadConfig(repoRoot);
+        const result = await commandBus.pollIfDue(repoRoot, 'userPromptSubmit', cfg?.companion?.commandBus, current);
+        if (result.statePatch)
+            state.patch(repoRoot, result.statePatch);
+        const block = commandBus.renderForAgent(result.events, result.reactionMode);
+        if (block) {
+            const out = {
+                hookSpecificOutput: {
+                    hookEventName: 'UserPromptSubmit',
+                    additionalContext: block,
+                },
+            };
+            process.stdout.write(JSON.stringify(out));
+            return 0;
+        }
+    }
     const userMessage = String(payload?.prompt ?? payload?.user_message ?? payload?.message ?? '').trim();
     const wrap = detectWrapPhrase(userMessage);
     if (wrap) {
@@ -487,11 +537,26 @@ function maybeSurfaceCoverage(repoRoot, current) {
     };
     process.stdout.write(JSON.stringify(out));
 }
-function handleStop(payload) {
+async function handleStop(payload) {
     const repoRoot = config.findRepoRoot(process.cwd());
     if (!repoRoot)
         return 0;
     const cfg = safeLoadConfig(repoRoot);
+    // Between-turn poll for the Agent Command Bus inbox (TRD §Pillar 1 Stop). Subject to
+    // the floor. When events arrive, surface as a top-level systemMessage (Stop has no
+    // hookSpecificOutput) and short-circuit — workbook sweep skips this turn.
+    {
+        const cur0 = state.read(repoRoot);
+        const result = await commandBus.pollIfDue(repoRoot, 'stop', cfg?.companion?.commandBus, cur0);
+        if (result.statePatch)
+            state.patch(repoRoot, result.statePatch);
+        const block = commandBus.renderForAgent(result.events, result.reactionMode);
+        if (block) {
+            const out = { systemMessage: block };
+            process.stdout.write(JSON.stringify(out));
+            return 0;
+        }
+    }
     const ws = cfg?.companion?.autoWorkbookUpdates || {};
     if (cfg?.companion?.safeMode === true)
         return silentExit();

package/dist/hooks/lib/state.js

@@ -93,6 +93,12 @@ exports.DEFAULT_COMPANION_STATE = Object.freeze({
     pendingWorkbookSweep: false,
     pendingWorkbookSweepReason: null,
     lastSeenVerifyCompletionTs: null,
+    commandBus: {
+        cursor: null,
+        lastPollTs: null,
+        consecutiveFailures: 0,
+        recentEventIds: [],
+    },
     metrics: exports.DEFAULT_COMPANION_METRICS,
 });
 function statePath(repoRoot) {

package/dist/hooks/types.d.ts

@@ -139,6 +139,7 @@ export interface CompanionState {
     pendingWorkbookSweep: boolean;
     pendingWorkbookSweepReason: string | null;
     lastSeenVerifyCompletionTs: string | null;
+    commandBus: CommandBusState;
     metrics: CompanionMetrics;
 }
 /**
@@ -198,12 +199,40 @@ export interface AuthoringConfig {
         enabled?: boolean;
     };
 }
+export type CommandBusHook = 'sessionStart' | 'userPromptSubmit' | 'stop' | 'postToolUse';
+export type CommandBusReactionMode = 'HALT_AND_REPLAN' | 'ACKNOWLEDGE_AND_CONTINUE' | 'SILENT_LOG';
+export interface CommandBusConfig {
+    enabled?: boolean;
+    pollHooks?: CommandBusHook[];
+    minPollIntervalSeconds?: number;
+    reactionMode?: CommandBusReactionMode;
+}
+export interface CommandBusState {
+    cursor: string | null;
+    lastPollTs: string | null;
+    consecutiveFailures: number;
+    recentEventIds: string[];
+}
+export interface InboxEvent {
+    eventId: string;
+    featureId: string;
+    eventType: string;
+    sourceType: string;
+    sourceId: string | null;
+    urgency: 'BLOCKING' | 'INFORMATIONAL';
+    payload: Record<string, unknown>;
+    createdTs: string;
+    ttlAt: string;
+    issuerType: string;
+    issuerId: string | null;
+}
 export interface CompanionConfig {
     companion?: {
         autoVerify?: AutoVerifyConfig;
         autoWorkbookUpdates?: AutoWorkbookUpdatesConfig;
         coverageNudges?: CoverageNudgesConfig;
         authoring?: AuthoringConfig;
+        commandBus?: CommandBusConfig;
         safeMode?: boolean;
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dezycro-ai/agent-plugin",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Official Dezycro plugin for AI coding agents (Claude Code today, more to come) — reverse-engineer your codebase into features, PRDs, TRDs, and live verification.",
   "bin": {
     "dezycro-setup": "./setup.js",

package/skills/init/SKILL.md

@@ -86,7 +86,19 @@ If yes, ask for:
 - API URL (e.g., `https://api.dev.example.com`)
 - Health check endpoint (default: same as local)
 
-## Step 6: Write Config
+## Step 6: Agent Command Bus Reaction Mode
+
+The Companion can poll Dezycro's per-feature Agent Command Bus inbox so the platform can deliver in-turn commands (today: invalidations from the workbook UI; future: recap, refocus, plan-check, …) to the agent. Ask the user how the agent should react when a **blocking** event arrives mid-feature:
+
+> When the platform sends a blocking event (e.g., a user invalidates an assumption in the workbook), how should the agent react?
+>
+> 1. **Halt and re-plan** (recommended) — pause current work at the next hook boundary, acknowledge in chat, re-plan before touching code again.
+> 2. **Acknowledge and keep going** — surface the event in the next reply, continue current work, do not silently reuse invalidated artifacts.
+> 3. **Silent log only** — record in transcript without interrupting chat. Not recommended for v1 invalidations.
+
+Capture the choice as one of `HALT_AND_REPLAN`, `ACKNOWLEDGE_AND_CONTINUE`, `SILENT_LOG`. If the user does not pick, default to `HALT_AND_REPLAN`.
+
+## Step 7: Write Config
 
 Create the `.dezycro/` directory and write `.dezycro/config.json`:
 
@@ -103,6 +115,14 @@ Create the `.dezycro/` directory and write `.dezycro/config.json`:
       "healthCheck": "curl -sf <apiUrl><healthPath>",
       "default": true
     }
+  },
+  "companion": {
+    "commandBus": {
+      "enabled": true,
+      "pollHooks": ["sessionStart", "userPromptSubmit", "stop", "postToolUse"],
+      "minPollIntervalSeconds": 60,
+      "reactionMode": "<HALT_AND_REPLAN | ACKNOWLEDGE_AND_CONTINUE | SILENT_LOG>"
+    }
   }
 }
 ```
@@ -112,16 +132,36 @@ Omit `setup` and `teardown` keys if the user skipped environment setup. Include
 Use the Bash tool to create the directory: `mkdir -p .dezycro`
 Use the Write tool to write the config file.
 
-## Step 7: Gitignore Check
+## Step 8: Companion API Token
+
+The Companion plugin needs a bearer token to read the Agent Command Bus inbox directly from the platform. This is **separate from the MCP server token** (the MCP token is configured in Claude Code's MCP settings; this token is read locally by the runner). Yes, that means setting the token in two places — by design, since the runner runs outside of MCP.
+
+Tell the user:
+
+> Create `.dezycro/companion-token.local.json` and paste your Dezycro API token. Get one from **Dezycro > Settings > API Keys** (same key you can use for MCP). Shape:
+>
+> ```json
+> { "token": "dzy_…" }
+> ```
+>
+> **Always gitignore this file** — it contains a real secret.
+
+Without this file the Companion silently skips command-bus polling (no errors, no surfaced events). You can always add it later.
+
+## Step 9: Gitignore Check
 
 Read `.gitignore` (if it exists) and check if it already covers `.dezycro/`. If not, suggest adding:
 
 ```
 # Dezycro local state
 .dezycro/active-feature.json
+.dezycro/companion-state.json
+.dezycro/companion-token.local.json
 .dezycro/bin/
 ```
 
+`.dezycro/companion-token.local.json` MUST be gitignored — it holds a real API token.
+
 Ask the user if they want `.dezycro/config.json` committed (recommended) or gitignored too. If they want it gitignored, add `.dezycro/` instead.
 
 ## Done