@skrr-ai/cli 0.1.115 → 0.1.117

package/dist/node_modules/@skrr-ai/inference-broker/dist/cjs/managed-inference-renewal.js

@@ -1,294 +1,153 @@
 "use strict";
-/**
- * OSK-3901 (ADR-105) — the managed lease renewal heartbeat.
- *
- * ── What it exists to fix ──────────────────────────────────────────────────
- *
- * `startManagedInferenceBroker` captures its credential and model scope once at
- * construction and never refreshes them, and a managed lease is bounded at 15
- * minutes. So an agentic turn that ran longer lost authorization mid-flight and
- * the relay answered `scope-denied`. The API can extend a lease now; nothing was
- * asking it to.
- *
- * ── Renew EARLY, and why that is correctness rather than caution ───────────
- *
- * The reservation reaper selects `{status:'active', expiresAt:{$lte:now}}` and
- * CASes per row, and the renewal CAS deliberately requires
- * `expiresAt: {$gt: now}` so it can never resurrect a row the reaper is closing.
- * Renewing late therefore does not merely risk a slow call — it risks an
- * UNRENEWABLE lease. The heartbeat fires at a fraction of the window, comfortably
- * inside the reaper's 60-second interval.
- *
- * ── One renewalId per intended extension ──────────────────────────────────
- *
- * The server distinguishes a replay from a refusal by checking whether the
- * winning reservation already carries the exact `renewalId`. So a caller reusing
- * one id for two DIFFERENT extensions would read the second as an idempotent
- * no-op and believe it had extended when it had not. Each tick therefore mints
- * its own id, and a RETRY of that tick reuses it.
- *
- * ── Failure discipline ────────────────────────────────────────────────────
- *
- * A denial is terminal and is reported as such. There is deliberately no
- * fall-back to an ambient credential: managed, BYOK and offline are separate
- * modes with separate custody, and silently becoming one of the others is the
- * failure invariant I4 exists to prevent. The loop's job on failure is to stop
- * and say why, not to keep the session alive by other means.
- *
- * ── TWO clocks on ONE heartbeat ───────────────────────────────────────────
- *
- * The lease is not the only thing that expires. The session CAPABILITY that
- * authenticates every relay call — and this loop's own renewals — has its own,
- * shorter TTL, and nothing used to refresh it: an hour in, the relay 401ed while
- * the lease was still well inside the ceiling its policy had bought.
- *
- * That refresh rides THIS timer rather than a second one. A second loop would
- * mean two independent stop conditions for one session, and a session whose lease
- * heartbeat is alive while its credential heartbeat is dead is a state nobody
- * would think to look for. The two clocks are checked on the same tick and stay
- * independent where it matters: a transient capability failure never stops the
- * lease heartbeat, and only a TERMINAL capability outcome — the ceiling, a
- * refusal, or our own token having lapsed — ends the session.
- *
- * ── Which clock actually reaches the ceiling ───────────────────────────────
- *
- * Both can name it, and on the shipped interactive profile the LEASE gets there
- * first. The lease renewal is refused once the ceiling is nearer than the window
- * it would ask for (300s by default), while the capability refresh is refused
- * only once the clamped grant falls under a 60s floor — so the lease dies about
- * three minutes before the capability fence could ever speak. That is why the
- * lease renewal must be able to report `ceiling` in its own right; a design that
- * carried the ceiling ONLY on the capability path had a stop reason that was
- * unreachable in the default configuration.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.scheduleRenewalDelay = scheduleRenewalDelay;
-exports.minimumCapabilityWindowMs = minimumCapabilityWindowMs;
-exports.startRenewalLoop = startRenewalLoop;
-const node_crypto_1 = require("node:crypto");
-/**
- * Fraction of the remaining window at which to renew.
- *
- * 0.6 rather than something closer to 1: the reaper interval is 60s and the
- * shortest permitted lease is 30s, so a later trigger can leave no room to
- * recover a single failed attempt before the lease becomes unrenewable.
- */
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var managed_inference_renewal_exports = {};
+__export(managed_inference_renewal_exports, {
+  minimumCapabilityWindowMs: () => minimumCapabilityWindowMs,
+  scheduleRenewalDelay: () => scheduleRenewalDelay,
+  startRenewalLoop: () => startRenewalLoop
+});
+module.exports = __toCommonJS(managed_inference_renewal_exports);
+var import_node_crypto = require("node:crypto");
 const RENEW_AT_FRACTION = 0.6;
-/** Never schedule closer than this, so a tiny window cannot become a busy loop. */
-const MIN_DELAY_MS = 1_000;
-/**
- * Floor between two capability refresh ATTEMPTS after a failure.
- *
- * The renew route is rate-limited to one call per 30s per (user, session) and
- * answers 429 past it, so an earlier retry cannot succeed — it can only consume
- * the window a genuine refresh needs. Applied even when the server named no
- * `Retry-After`, because the lease heartbeat's own tick can be as short as a
- * second and this check rides that tick.
- */
-const CAPABILITY_RETRY_MIN_DELAY_MS = 30_000;
+const MIN_DELAY_MS = 1e3;
+const CAPABILITY_RETRY_MIN_DELAY_MS = 3e4;
 function scheduleRenewalDelay(expiresInMs) {
-    if (!Number.isFinite(expiresInMs) || expiresInMs <= 0)
-        return MIN_DELAY_MS;
-    return Math.max(MIN_DELAY_MS, Math.floor(expiresInMs * RENEW_AT_FRACTION));
+  if (!Number.isFinite(expiresInMs) || expiresInMs <= 0)
+    return MIN_DELAY_MS;
+  return Math.max(MIN_DELAY_MS, Math.floor(expiresInMs * RENEW_AT_FRACTION));
 }
-/**
- * The shortest capability window this lease cadence can still refresh IN TIME.
- *
- * The two clocks share one timer, so the capability refresh can only fire on a
- * lease tick. It comes due with `1 - RENEW_AT_FRACTION` of its window left, and
- * the worst case is a tick that fired just before that instant — the next one is
- * a whole lease interval later, and it has to land before the token actually
- * dies. So the capability window must exceed `leaseTick / (1 - RENEW_AT_FRACTION)`,
- * which for the shipped 0.6 fraction is 1.5x the lease window.
- *
- * Exported because NOTHING pinned this relation and it is settable from two
- * unrelated places: `OVERSKY_SESSION_TOKEN_TTL_S` sizes the capability,
- * `OVERSKY_GATEWAY_KEY_TTL` sizes the lease renewal window. At the supported
- * gateway TTL of 15 minutes, a token TTL of 1350s or less means the FIRST refresh
- * presents an already-dead token — the feature silently does not apply, in a
- * configuration that looks configured. The host warns; this function is the
- * arithmetic it warns from, so the number and the schedule cannot drift apart.
- */
 function minimumCapabilityWindowMs(leaseWindowMs) {
-    // The real armed delay, not `leaseWindowMs * RENEW_AT_FRACTION`: a tiny lease
-    // floors at MIN_DELAY_MS, and the floor is what the refresh would actually wait.
-    return Math.ceil(scheduleRenewalDelay(leaseWindowMs) / (1 - RENEW_AT_FRACTION));
+  return Math.ceil(scheduleRenewalDelay(leaseWindowMs) / (1 - RENEW_AT_FRACTION));
 }
 function startRenewalLoop(options) {
-    const setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
-    const clearTimer = options.clearTimer ?? ((h) => clearTimeout(h));
-    const now = options.now ?? (() => Date.now());
-    const maxTransportRetries = options.maxTransportRetries ?? 2;
-    let handle = null;
-    let stopped = false;
-    let renewals = 0;
-    /**
-     * When the capability is next due for a refresh, as an absolute instant, or
-     * `null` when this loop does not know its clock.
-     *
-     * `null` is the load-bearing state, not a placeholder: an unknown expiry means
-     * there is no honest schedule, and the pre-change behaviour — a capability that
-     * simply runs out — is strictly better than one refreshed on a guess.
-     */
-    let capabilityDueAtMs = null;
-    const finish = (reason, detail) => {
-        if (stopped)
-            return;
-        stopped = true;
-        if (handle != null)
-            clearTimer(handle);
-        handle = null;
-        options.onStop?.(reason, detail);
-    };
-    const arm = (expiresInMs) => {
-        if (stopped)
-            return;
-        handle = setTimer(() => {
-            void tick();
-        }, scheduleRenewalDelay(expiresInMs));
-        // Never hold the process open for a renewal. A daemon that cannot exit
-        // because a lease timer is pending would outlive the session it serves.
-        if (handle && typeof handle.unref === 'function') {
-            handle.unref();
-        }
-    };
-    /**
-     * Put the capability's next refresh on the SAME cadence rule the lease uses.
-     *
-     * It shares `RENEW_AT_FRACTION` with the lease, so both clocks answer "renew at
-     * 60% of the window you were actually granted". It deliberately does NOT reuse
-     * `scheduleRenewalDelay`'s one-second floor: this value does not arm a timer;
-     * it only decides whether the next bounded lease tick should refresh first. The
-     * floor can otherwise move a short capability's due instant *past* an earlier
-     * lease tick, causing that renewal to present the capability it was meant to
-     * replace. The lease timer remains rate-limited by its own floor.
-     *
-     * An expiry that is missing, unparseable or already past yields `null`: those
-     * are all "we do not know when this dies", and `scheduleRenewalDelay` would
-     * otherwise turn them into "one second from now".
-     */
-    const scheduleCapability = (expiresAtMs, observedAtMs) => {
-        const remaining = typeof expiresAtMs === 'number' ? expiresAtMs - observedAtMs : Number.NaN;
-        capabilityDueAtMs =
-            Number.isFinite(remaining) && remaining > 0
-                ? observedAtMs + Math.max(0, Math.floor(remaining * RENEW_AT_FRACTION))
-                : null;
-    };
-    /**
-     * Refresh the capability if it is due. Returns false only when the caller must
-     * stop — the loop has already been finished with the right reason by then.
-     *
-     * ONE attempt per tick, deliberately unlike the lease's immediate retries: those
-     * fire with no backoff, and three of them against a route capped at one call per
-     * 30s per session would turn a single blip into a self-inflicted rate limit. The
-     * next tick is the retry.
-     */
-    const refreshCapabilityIfDue = async () => {
-        const refresh = options.refreshCapability;
-        if (!refresh || capabilityDueAtMs == null || now() < capabilityDueAtMs)
-            return true;
-        let outcome;
-        try {
-            outcome = await refresh();
-        }
-        catch (err) {
-            outcome = {
-                ok: false,
-                reason: err instanceof Error ? err.message : 'capability refresh threw',
-            };
-        }
-        if (stopped)
-            return false;
-        if (outcome.ceiling) {
-            // The money's ceiling is immutable, so no later attempt can succeed and no
-            // lease renewal on this tick could either — they are bounded by the same
-            // instant.
-            finish('ceiling', outcome.reason);
-            return false;
-        }
-        if (outcome.expired) {
-            // Terminal like a denial and reported as neither: a refresh presents the
-            // token it is replacing, so a dead one leaves nothing to present — but the
-            // server decided nothing here, and saying it refused us would be a claim
-            // about a decision that was never made.
-            finish('expired', outcome.reason);
-            return false;
-        }
-        if (outcome.denied) {
-            finish('denied', outcome.reason);
-            return false;
-        }
-        if (outcome.ok) {
-            scheduleCapability(outcome.expiresAtMs, now());
-            return true;
-        }
-        // Transient. Deliberately does NOT abort this tick's lease renewal: dropping
-        // the lease heartbeat because the token refresh had a bad minute would
-        // re-create, from the other side, the outage this whole change exists to fix.
-        // The refresh is proactive, so there is still window left to try again.
-        capabilityDueAtMs = now() + Math.max(outcome.retryAfterMs ?? 0, CAPABILITY_RETRY_MIN_DELAY_MS);
-        return true;
-    };
-    const tick = async () => {
-        if (stopped)
-            return;
-        // The capability FIRST, because the lease renewal below authenticates with it:
-        // spending this tick's attempts on a credential that is about to expire is how
-        // a healthy lease ends up unrenewable.
-        if (!(await refreshCapabilityIfDue()))
-            return;
-        // One id per intended extension, reused across transport retries of THIS
-        // tick. A fresh id per retry would let a lost response become a second real
-        // extension; a shared id across ticks would make a genuine second extension
-        // read as an idempotent no-op.
-        const renewalId = (0, node_crypto_1.randomUUID)();
-        for (let attempt = 0; attempt <= maxTransportRetries; attempt++) {
-            if (stopped)
-                return;
-            let outcome;
-            try {
-                outcome = await options.renew({ renewalId });
-            }
-            catch (err) {
-                outcome = { ok: false, reason: err instanceof Error ? err.message : 'renewal threw' };
-            }
-            if (outcome.ok) {
-                renewals += 1;
-                arm(outcome.expiresInMs ?? options.initialExpiresInMs);
-                return;
-            }
-            if (outcome.ceiling) {
-                // Checked BEFORE `denied`, and separately from it, because this is the
-                // refusal a supervised session is EXPECTED to end on. Every other 4xx here
-                // means something went wrong; this one means the session used exactly the
-                // window it was authorized, and the user needs to be told that and not
-                // that "renewal was refused".
-                finish('ceiling', outcome.reason);
-                return;
-            }
-            if (outcome.exhausted) {
-                // Before `denied` for the same reason `ceiling` is: the server DID answer
-                // 4xx, so the generic branch would catch it and report "renewal was
-                // refused" for a session that simply ran out of money. The detail carries
-                // `resetAt` when the server sent one, so the message layer can offer a
-                // time without re-deriving whether one exists.
-                finish('exhausted', outcome.resetAt ?? outcome.reason);
-                return;
-            }
-            if (outcome.denied) {
-                // A decision, not a blip. Retrying asks the identical question.
-                finish('denied', outcome.reason);
-                return;
-            }
-        }
-        finish('unavailable', 'managed lease renewal transport exhausted');
-    };
-    scheduleCapability(options.capabilityExpiresAtMs, now());
-    arm(options.initialExpiresInMs);
-    return {
-        stop: () => finish('stopped'),
-        get renewals() {
-            return renewals;
-        },
-    };
+  const setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+  const clearTimer = options.clearTimer ?? ((h) => clearTimeout(h));
+  const now = options.now ?? (() => Date.now());
+  const maxTransportRetries = options.maxTransportRetries ?? 2;
+  let handle = null;
+  let stopped = false;
+  let renewals = 0;
+  let capabilityDueAtMs = null;
+  const finish = (reason, detail) => {
+    if (stopped)
+      return;
+    stopped = true;
+    if (handle != null)
+      clearTimer(handle);
+    handle = null;
+    options.onStop?.(reason, detail);
+  };
+  const arm = (expiresInMs) => {
+    if (stopped)
+      return;
+    handle = setTimer(() => {
+      void tick();
+    }, scheduleRenewalDelay(expiresInMs));
+    if (handle && typeof handle.unref === "function") {
+      handle.unref();
+    }
+  };
+  const scheduleCapability = (expiresAtMs, observedAtMs) => {
+    const remaining = typeof expiresAtMs === "number" ? expiresAtMs - observedAtMs : Number.NaN;
+    capabilityDueAtMs = Number.isFinite(remaining) && remaining > 0 ? observedAtMs + Math.max(0, Math.floor(remaining * RENEW_AT_FRACTION)) : null;
+  };
+  const refreshCapabilityIfDue = async () => {
+    const refresh = options.refreshCapability;
+    if (!refresh || capabilityDueAtMs == null || now() < capabilityDueAtMs)
+      return true;
+    let outcome;
+    try {
+      outcome = await refresh();
+    } catch (err) {
+      outcome = {
+        ok: false,
+        reason: err instanceof Error ? err.message : "capability refresh threw"
+      };
+    }
+    if (stopped)
+      return false;
+    if (outcome.ceiling) {
+      finish("ceiling", outcome.reason);
+      return false;
+    }
+    if (outcome.expired) {
+      finish("expired", outcome.reason);
+      return false;
+    }
+    if (outcome.denied) {
+      finish("denied", outcome.reason);
+      return false;
+    }
+    if (outcome.ok) {
+      scheduleCapability(outcome.expiresAtMs, now());
+      return true;
+    }
+    capabilityDueAtMs = now() + Math.max(outcome.retryAfterMs ?? 0, CAPABILITY_RETRY_MIN_DELAY_MS);
+    return true;
+  };
+  const tick = async () => {
+    if (stopped)
+      return;
+    if (!await refreshCapabilityIfDue())
+      return;
+    const renewalId = (0, import_node_crypto.randomUUID)();
+    for (let attempt = 0; attempt <= maxTransportRetries; attempt++) {
+      if (stopped)
+        return;
+      let outcome;
+      try {
+        outcome = await options.renew({ renewalId });
+      } catch (err) {
+        outcome = { ok: false, reason: err instanceof Error ? err.message : "renewal threw" };
+      }
+      if (outcome.ok) {
+        renewals += 1;
+        arm(outcome.expiresInMs ?? options.initialExpiresInMs);
+        return;
+      }
+      if (outcome.ceiling) {
+        finish("ceiling", outcome.reason);
+        return;
+      }
+      if (outcome.exhausted) {
+        finish("exhausted", outcome.resetAt ?? outcome.reason);
+        return;
+      }
+      if (outcome.denied) {
+        finish("denied", outcome.reason);
+        return;
+      }
+    }
+    finish("unavailable", "managed lease renewal transport exhausted");
+  };
+  scheduleCapability(options.capabilityExpiresAtMs, now());
+  arm(options.initialExpiresInMs);
+  return {
+    stop: () => finish("stopped"),
+    get renewals() {
+      return renewals;
+    }
+  };
 }
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  minimumCapabilityWindowMs,
+  scheduleRenewalDelay,
+  startRenewalLoop
+});

package/dist/node_modules/@skrr-ai/inference-broker/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skrr-ai/inference-broker",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "main": "dist/cjs/index.js",
   "types": "dist/cjs/index.d.ts",
   "exports": {

package/dist/signal-command.d.ts

@@ -2,10 +2,10 @@ import { BaseCommand } from './base-command';
 /** Signals have no personal-workspace fallback. */
 export declare abstract class SignalCommand extends BaseCommand {
     static baseFlags: {
-        workspace: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
-        bare: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
-        token: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
-        profile: import("@oclif/core/lib/interfaces").OptionFlag<string | undefined, import("@oclif/core/lib/interfaces").CustomOptions>;
-        raw: import("@oclif/core/lib/interfaces").BooleanFlag<boolean>;
+        workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        bare: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        token: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        raw: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
 }

package/docs/v1/lookback-plans.md

@@ -86,3 +86,61 @@ skrr followups plans observability --agent YOUR_AGENT_ID --json
 Use the current revision returned by `show`. A stale edit returns `LOOKBACK_CONFLICT` with HTTP 409; reread before deciding whether to edit again. Revision JSON is the full authored plan itself, with the exact original source and existing step IDs. Start from `plan.json`, preserve IDs from `show`, and edit pending instructions/times. Do not resubmit the full `show` response: server fields such as `state`, `runAt`, `expiresAt`, outcomes and claims are not authoring input. Completed evaluations consume the same lifetime allowance after edits.
 
 Cancellation is idempotent and fences remaining work; it does not retract a message already delivered. `observability` reports a bounded sample, not lifetime totals. Normal account authority, budgets, runtime support and delivery policies still apply. No feature-flag enrollment or special two-person activation is needed.
+
+## Conversation follow-up controls
+
+One completed reply can produce several independently accepted follow-up schedules. Inspect the accepted commitments for a conversation or message through the dedicated factual projection:
+
+```sh
+skrr followups plans accepted --agent YOUR_AGENT_ID --conversation YOUR_CONVERSATION_ID --json
+skrr followups plans accepted --all-agents --conversation YOUR_CONVERSATION_ID --message YOUR_MESSAGE_ID --json
+```
+
+These reads return accepted purposes, timing, states, revisions and available controls. Private decision requests, intent arrays, decision bases, candidate messages and inspection instructions are excluded. A scheduled opportunity may produce a useful message or stay silent; it does not promise a notification. `show` and `list` also use the factual projection for these schedules. Keep your original authored input when revising an explicit legacy plan; the factual projection cannot reconstruct private inspection instructions.
+
+Use `cancel PLAN_ID --revision CURRENT_REVISION` to cancel one schedule. To cancel several independently, save a JSON file with each current revision:
+
+```json
+{
+  "plans": [
+    { "id": "FIRST_PLAN_ID", "expectedRevision": 4 },
+    { "id": "SECOND_PLAN_ID", "expectedRevision": 2 }
+  ],
+  "reason": "No longer needed"
+}
+```
+
+```sh
+skrr followups plans cancel-batch --from-json cancellations.json --json
+```
+
+The response reports every plan's actual outcome. One stale revision or failure does not roll back another cancellation. A partial or unconfirmed outcome sets a nonzero exit status. After a conflict, read the current revision before deciding on another change. After a transport failure the CLI reads each known plan and reports an unconfirmed mutation; it never blindly repeats the batch. Observing a cancelled plan does not prove which request cancelled it.
+
+## Continuity preferences
+
+Read account defaults or an Agent's effective settings and override revision:
+
+```sh
+skrr followups plans preferences --json
+skrr followups plans preferences --agent YOUR_AGENT_ID --json
+```
+
+`revision` in the response belongs to the selected scope. Use that exact value as `expectedRevision` when changing that scope; do not substitute the account revision for an Agent override. Save an update such as this to `preferences.json`:
+
+```json
+{
+  "expectedRevision": 0,
+  "proactiveContributions": false,
+  "automaticReturns": false,
+  "allowHostedInference": false
+}
+```
+
+```sh
+skrr followups plans preferences set --from-json preferences.json --json
+skrr followups plans preferences set --agent YOUR_AGENT_ID --from-json preferences.json --json
+```
+
+Only include the settings you intend to change. `allowHostedInference: true` permits private platform continuity analysis separately from the primary Agent's inference route, including for a locally run Agent. It grants no tools and does not guarantee inference availability. `false` declines hosted continuity analysis; `null` inherits the applicable default. To remove all three Agent overrides, use an Agent-scoped update containing only `expectedRevision` and `inherit: true` (plus `agentId` when not using `--agent`). An account scope cannot inherit an Agent's settings.
+
+A stale revision is refused. If a mutation's response is lost, the CLI reads the same scope and reports an unconfirmed outcome without retrying the write. Decide on a new change only after reading its current revision.