@dezycro-ai/agent-plugin 2.1.0 → 2.1.2

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

@@ -8,7 +8,11 @@
  *   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++.
+ * * On non-2xx / network failure: cursor stays put, consecutiveFailures++, and
+ *   `lastAttemptTs` advances so the floor throttles repeated failures. Once
+ *   failures cross `circuitBreakerThreshold` the floor grows exponentially
+ *   (capped at `maxBackoffSeconds`), so an unreachable endpoint is not polled on
+ *   every hook fire. A single success resets the counter and the interval.
  *
  * 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).
@@ -27,7 +31,15 @@ interface ResolvedConfig {
     hooks: ReadonlySet<CommandBusHook>;
     minPollIntervalSeconds: number;
     reactionMode: CommandBusReactionMode;
+    circuitBreakerThreshold: number;
+    maxBackoffSeconds: number;
 }
+/**
+ * Effective poll interval given the number of consecutive failures so far.
+ * Returns the base interval until `threshold` failures, then doubles per extra
+ * failure, capped at `maxSeconds`. Never throws.
+ */
+export declare function backoffSeconds(baseSeconds: number, consecutiveFailures: number, threshold: number, maxSeconds: number): number;
 /**
  * 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.
@@ -49,5 +61,6 @@ export declare const _internals: {
     renderEvent: typeof renderEvent;
     reactionGuidance: typeof reactionGuidance;
     trimRecent: typeof trimRecent;
+    backoffSeconds: typeof backoffSeconds;
 };
 export {};

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

@@ -8,7 +8,11 @@
  *   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++.
+ * * On non-2xx / network failure: cursor stays put, consecutiveFailures++, and
+ *   `lastAttemptTs` advances so the floor throttles repeated failures. Once
+ *   failures cross `circuitBreakerThreshold` the floor grows exponentially
+ *   (capped at `maxBackoffSeconds`), so an unreachable endpoint is not polled on
+ *   every hook fire. A single success resets the counter and the interval.
  *
  * 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).
@@ -52,9 +56,11 @@ var __importStar = (this && this.__importStar) || (function () {
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports._internals = void 0;
+exports.backoffSeconds = backoffSeconds;
 exports.pollIfDue = pollIfDue;
 exports.renderForAgent = renderForAgent;
 const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const logging = __importStar(require("./logging"));
 const DEFAULT_HOOKS = [
@@ -67,6 +73,24 @@ const DEFAULT_MIN_POLL_INTERVAL_SECONDS = 60;
 const DEFAULT_REACTION_MODE = 'HALT_AND_REPLAN';
 const RECENT_EVENT_IDS_CAP = 200;
 const POLL_LIMIT = 100;
+// After this many consecutive failures the poll interval starts doubling per
+// extra failure (capped at maxBackoffSeconds) so an unreachable inbox endpoint
+// — e.g. a default `local` env that isn't running — stops being polled on every
+// hook fire. Self-heals: a single success resets consecutiveFailures to 0.
+const DEFAULT_CIRCUIT_BREAKER_THRESHOLD = 3;
+const DEFAULT_MAX_BACKOFF_SECONDS = 1800;
+/**
+ * Effective poll interval given the number of consecutive failures so far.
+ * Returns the base interval until `threshold` failures, then doubles per extra
+ * failure, capped at `maxSeconds`. Never throws.
+ */
+function backoffSeconds(baseSeconds, consecutiveFailures, threshold, maxSeconds) {
+    if (consecutiveFailures < threshold)
+        return baseSeconds;
+    const extra = consecutiveFailures - threshold + 1;
+    const scaled = baseSeconds * Math.pow(2, extra);
+    return Math.min(scaled, maxSeconds);
+}
 /**
  * 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.
@@ -84,11 +108,17 @@ async function pollIfDue(repoRoot, hookEvent, config, state) {
     // 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);
+    // Throttle from the last ATTEMPT (success or failure), not just the last
+    // success — otherwise a never-succeeding endpoint (lastPollTs stays null) is
+    // polled on every hook fire. The floor grows via exponential backoff once
+    // consecutive failures cross the circuit-breaker threshold.
+    const lastAttempt = cbState.lastAttemptTs ?? cbState.lastPollTs;
+    if (hookEvent !== 'sessionStart' && lastAttempt) {
+        const lastMs = Date.parse(lastAttempt);
         if (!Number.isNaN(lastMs)) {
+            const floorSeconds = backoffSeconds(resolved.minPollIntervalSeconds, cbState.consecutiveFailures ?? 0, resolved.circuitBreakerThreshold, resolved.maxBackoffSeconds);
             const ageSeconds = (Date.now() - lastMs) / 1000;
-            if (ageSeconds < resolved.minPollIntervalSeconds)
+            if (ageSeconds < floorSeconds)
                 return empty;
         }
     }
@@ -104,6 +134,7 @@ async function pollIfDue(repoRoot, hookEvent, config, state) {
         return empty;
     }
     const since = hookEvent === 'sessionStart' ? null : cbState.cursor;
+    const attemptTs = new Date().toISOString();
     try {
         const fetched = await fetchInbox(apiUrl, feature, token, since);
         const seen = new Set(cbState.recentEventIds ?? []);
@@ -113,6 +144,7 @@ async function pollIfDue(repoRoot, hookEvent, config, state) {
             commandBus: {
                 cursor: fetched.nextCursor || cbState.cursor,
                 lastPollTs: fetched.serverTs,
+                lastAttemptTs: attemptTs,
                 consecutiveFailures: 0,
                 recentEventIds: newRing,
             },
@@ -127,16 +159,21 @@ async function pollIfDue(repoRoot, hookEvent, config, state) {
         return { events: fresh, statePatch: patch, reactionMode };
     }
     catch (e) {
+        const consecutiveFailures = (cbState.consecutiveFailures ?? 0) + 1;
         const patch = {
             commandBus: {
                 ...cbState,
-                consecutiveFailures: (cbState.consecutiveFailures ?? 0) + 1,
+                lastAttemptTs: attemptTs,
+                consecutiveFailures,
             },
         };
+        const nextFloor = backoffSeconds(resolved.minPollIntervalSeconds, consecutiveFailures, resolved.circuitBreakerThreshold, resolved.maxBackoffSeconds);
         logging.info(repoRoot, 'command_bus_poll_failed', {
             hookEvent,
             error: e instanceof Error ? e.message : String(e),
-            consecutiveFailures: patch.commandBus.consecutiveFailures,
+            consecutiveFailures,
+            nextPollAfterSeconds: nextFloor,
+            backoff: consecutiveFailures >= resolved.circuitBreakerThreshold,
         });
         return { events: [], statePatch: patch, reactionMode };
     }
@@ -189,7 +226,9 @@ function resolveConfig(c) {
     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 };
+    const circuitBreakerThreshold = Math.max(1, c?.circuitBreakerThreshold ?? DEFAULT_CIRCUIT_BREAKER_THRESHOLD);
+    const maxBackoffSeconds = Math.max(minPollIntervalSeconds, c?.maxBackoffSeconds ?? DEFAULT_MAX_BACKOFF_SECONDS);
+    return { enabled, hooks, minPollIntervalSeconds, reactionMode, circuitBreakerThreshold, maxBackoffSeconds };
 }
 function readActiveFeature(repoRoot) {
     try {
@@ -243,17 +282,27 @@ function readDezycroConfig(repoRoot) {
     }
 }
 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;
+    // Project-local override first, then the user-global token written by
+    // `dezycro-setup` (`~/.dezycro/token.json`). Typical install needs no
+    // per-repo file at all.
+    const candidates = [
+        path.join(repoRoot, '.dezycro', 'companion-token.local.json'),
+        path.join(os.homedir(), '.dezycro', 'token.json'),
+    ];
+    for (const p of candidates) {
+        try {
+            if (!fs.existsSync(p))
+                continue;
+            const raw = JSON.parse(fs.readFileSync(p, 'utf8'));
+            const token = raw.token;
+            if (typeof token === 'string' && token.length > 0)
+                return token;
+        }
+        catch {
+            // Try the next candidate.
+        }
     }
+    return null;
 }
 async function fetchInbox(apiUrl, feature, token, since) {
     const url = new URL(`${apiUrl}/api/v1/workspaces/${feature.workspaceId}/features/${feature.featureId}/inbox`);
@@ -304,4 +353,5 @@ exports._internals = {
     renderEvent,
     reactionGuidance,
     trimRecent,
+    backoffSeconds,
 };

package/dist/hooks/lib/router.js

@@ -50,6 +50,7 @@ const config = __importStar(require("./config"));
 const state = __importStar(require("./state"));
 const logging = __importStar(require("./logging"));
 const verify = __importStar(require("./verify"));
+const publishSpec = __importStar(require("./publish-spec"));
 const controllerMatch = __importStar(require("./controller-match"));
 const authoring = __importStar(require("./authoring"));
 const qualityGate = __importStar(require("./quality-gate"));
@@ -509,10 +510,57 @@ async function handleUserPromptSubmit(payload) {
             }
         }
     }
+    // Pillar 2 — persistent publish-spec/verify reminder. The PostToolUse pulse
+    // nudge only fires on the exact edit that touches a controller path (and only
+    // once pulseCount crosses the threshold), so endpoint changes routinely go
+    // un-surfaced. Re-surface on every UserPromptSubmit while needsSpecPublish is
+    // set, so the agent is reminded each turn until it publishes the spec. Gated
+    // by companion.autoVerify.autoPublishSpecOnControllerChange (default true).
+    {
+        const specNudge = buildPublishSpecNudge(repoRoot);
+        if (specNudge) {
+            logging.info(repoRoot, 'publish_spec_nudge', { paths: specNudge.count });
+            const out = {
+                hookSpecificOutput: {
+                    hookEventName: 'UserPromptSubmit',
+                    additionalContext: specNudge.text,
+                },
+            };
+            process.stdout.write(JSON.stringify(out));
+            return 0;
+        }
+    }
     maybeSurfaceCoverage(repoRoot, current);
     process.stdout.write('{}');
     return 0;
 }
+/**
+ * Build the persistent publish-spec/verify reminder, or null when nothing is
+ * pending or the feature is disabled. Surfaced on every UserPromptSubmit while
+ * `needsSpecPublish` is set; clears automatically once `/dezycro:publish-spec`
+ * resets the flags.
+ */
+function buildPublishSpecNudge(repoRoot) {
+    const cfg = safeLoadConfig(repoRoot);
+    const av = (cfg && cfg.companion && cfg.companion.autoVerify) || {};
+    if (av.autoPublishSpecOnControllerChange === false)
+        return null;
+    const check = publishSpec.needsPublishBeforeVerify(repoRoot);
+    if (!check.needed || check.controllerPaths.length === 0)
+        return null;
+    const MAX_LISTED = 8;
+    const paths = check.controllerPaths;
+    const shown = paths.slice(0, MAX_LISTED).map((p) => '  - ' + p);
+    if (paths.length > MAX_LISTED)
+        shown.push('  - …and ' + (paths.length - MAX_LISTED) + ' more');
+    const text = '[Dezycro Companion] ' + paths.length + ' controller/API file(s) changed since the last published spec:\n' +
+        shown.join('\n') + '\n\n' +
+        'New or changed endpoints are NOT yet reflected in the published OpenAPI spec, so verification ' +
+        'cannot see them. Before continuing, run `/dezycro:publish-spec` to upload the updated spec (this ' +
+        'regenerates the JEP), then `/dezycro:verify` to check the feature against it. This reminder repeats ' +
+        'each turn until the spec is published and clears automatically after `/dezycro:publish-spec`.';
+    return { text, count: paths.length };
+}
 function maybeSurfaceCoverage(repoRoot, current) {
     const cfg = safeLoadConfig(repoRoot);
     if (cfg?.companion?.coverageNudges?.enabled === false)

package/dist/hooks/lib/state.js

@@ -96,6 +96,7 @@ exports.DEFAULT_COMPANION_STATE = Object.freeze({
     commandBus: {
         cursor: null,
         lastPollTs: null,
+        lastAttemptTs: null,
         consecutiveFailures: 0,
         recentEventIds: [],
     },

package/dist/hooks/types.d.ts

@@ -206,10 +206,25 @@ export interface CommandBusConfig {
     pollHooks?: CommandBusHook[];
     minPollIntervalSeconds?: number;
     reactionMode?: CommandBusReactionMode;
+    /**
+     * After this many consecutive poll failures the effective poll interval grows
+     * exponentially (backoff) so an unreachable inbox endpoint stops being polled
+     * on every hook fire. Defaults to 3.
+     */
+    circuitBreakerThreshold?: number;
+    /** Upper bound (seconds) on the backed-off poll interval. Defaults to 1800 (30m). */
+    maxBackoffSeconds?: number;
 }
 export interface CommandBusState {
     cursor: string | null;
+    /** Timestamp of the last SUCCESSFUL poll (server clock). Used as the dedup/cursor anchor. */
     lastPollTs: string | null;
+    /**
+     * Timestamp of the last poll ATTEMPT (success or failure, client clock). The
+     * min-interval / backoff floor is measured from here so repeated failures are
+     * throttled even before a first success exists.
+     */
+    lastAttemptTs?: string | null;
     consecutiveFailures: number;
     recentEventIds: string[];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dezycro-ai/agent-plugin",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "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/setup.js

@@ -1,11 +1,14 @@
 #!/usr/bin/env node
 
 const { execSync } = require("child_process");
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
 const readline = require("readline");
 
 const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
 
-console.log(`\n  Dezycro MCP Setup`);
+console.log(`\n  Dezycro Setup`);
 console.log(`  Get your API key from Dezycro → Settings → API Keys\n`);
 
 rl.question("  API key (dzy_...): ", (apiKey) => {
@@ -17,19 +20,34 @@ rl.question("  API key (dzy_...): ", (apiKey) => {
     process.exit(1);
   }
 
-  const apiUrl = "https://mcp.dezycro.ai";
+  const mcpUrl = "https://mcp.dezycro.ai";
 
+  // 1. Configure Claude Code MCP server.
   try {
     execSync(
-      `claude mcp add --transport http dezycro "${apiUrl}/mcp" --header "Authorization: Bearer ${apiKey}"`,
+      `claude mcp add --transport http dezycro "${mcpUrl}/mcp" --header "Authorization: Bearer ${apiKey}"`,
       { stdio: "inherit" }
     );
     console.log(`\n  ✓ Dezycro MCP configured`);
-    console.log(`\n  You're all set! In Claude Code run: /dezycro:import-features\n`);
   } catch (err) {
     console.error(`\n  Failed to configure MCP. Run manually:`);
-    console.error(`  claude mcp add --transport http dezycro "${apiUrl}/mcp" --header "Authorization: Bearer ${apiKey}"\n`);
+    console.error(`  claude mcp add --transport http dezycro "${mcpUrl}/mcp" --header "Authorization: Bearer ${apiKey}"\n`);
   }
 
+  // 2. Save the user-global Companion token so companion-runner can poll the
+  //    Agent Command Bus without per-repo config. Project-local
+  //    .dezycro/companion-token.local.json still overrides this.
+  try {
+    const globalDir = path.join(os.homedir(), ".dezycro");
+    const globalTokenPath = path.join(globalDir, "token.json");
+    fs.mkdirSync(globalDir, { recursive: true, mode: 0o700 });
+    fs.writeFileSync(globalTokenPath, JSON.stringify({ token: apiKey }, null, 2), { mode: 0o600 });
+    console.log(`  ✓ Companion token saved to ${globalTokenPath}`);
+  } catch (err) {
+    console.error(`  Failed to save companion token: ${err.message}`);
+    console.error(`  Drop it manually at ~/.dezycro/token.json: {"token": "${apiKey}"}\n`);
+  }
+
+  console.log(`\n  You're all set! In Claude Code run: /dezycro:import-features\n`);
   rl.close();
 });