@revealui/ai 1.0.7 → 1.2.2

package/README.md

@@ -357,6 +357,28 @@ import { AgentRuntime } from '@revealui/ai/orchestration/runtime'
 const runtime = new AgentRuntime()
 ```
 
+#### Intentional dual: interactive runtime and governed receipts
+
+`AgentRuntime.executeTask` and `StreamingAgentRuntime.streamTask` are the interactive product loops. `runGovernedTask` (Apify actor `@revealui/apify-actor-governed-run`) is the governed receipt loop. Both call tools in a loop. They stay separate: receipts need an ordered action log plus charge and step caps; the interactive runtimes stay open until the model finishes, the iteration cap, or Studio LoopGuard says the loop is not advancing. Do not merge them.
+
+#### Studio LoopGuard (GAP-362)
+
+When the RevDev daemon socket is reachable (`REVEALUI_SOCKET`, otherwise `~/.local/share/revealui/harness.sock`), both interactive runtimes call `loop.arm` once per task and `loop.tick` after each model iteration. `loop.status` reads the loop. This package does not call `loop.stop`. `session.end` and `harness.prune` reap loops on the daemon (`packages/ai/src/orchestration/loop-guard.ts:4-12`).
+
+Fail-open: a missing socket returns immediately. A socket that refuses the connection or never answers is bounded by `timeoutMs` (default 750) and then ignored. The task does not throw and does not change its result.
+
+An iteration is advancing when the model returns a final answer, or when at least one tool runs that was not a duplicate of an earlier call in the same task (`packages/ai/src/orchestration/loop-guard.ts:132`). Duplicate-only rounds send `advanced: false`.
+
+No-op limit: omit `noopLimit` and the daemon applies 3 (`DAEMON_LOOP_NOOP_LIMIT`, RevDev `DEFAULT_LOOP_NOOP_LIMIT`) (`packages/ai/src/orchestration/loop-guard.ts:27`). This package does not keep a second counter. When `loop.tick` returns `stop: true` or `status: not_advancing`, the interactive runtime stops and surfaces `lastSignal` (`packages/ai/src/orchestration/loop-guard.ts:239`). `intervalMs` defaults to 60000 so an interactive tool loop is not flagged as a sub-minute idle poll (`packages/ai/src/orchestration/loop-guard.ts:34`). The runtime does not sleep for that interval.
+
+The actor id is the cached Studio session (`daemon-sessions/<pid>.id`, then `<ppid>.id`) when one exists, otherwise `revealui-product-runtime`.
+
+`runGovernedTask` does not call LoopGuard. Do not merge it with `AgentRuntime`.
+
+Do not boot the MCP Hypervisor silent process health loop without a WIRE mount and a credential owner (`packages/mcp/src/hypervisor.ts:999`).
+
+Pass `loopGuard: false` only when a caller must not report, including tests. The default wires whenever the daemon answers.
+
 ### Tools
 
 Tool registry and execution system with MCP integration.

package/dist/llm/providers/typesafe-jev.d.ts

@@ -0,0 +1,53 @@
+/**
+ * TypeSafe Jev — System One decision adapter.
+ *
+ * Not a chat model. Send state plus typed questions. The response is
+ * choices, scores, and noul probabilities. No TypeSafe SDK: one HTTPS POST.
+ * The key is the caller's TYPESAFE_API_KEY. RevealUI does not host one.
+ *
+ * Docs: https://docs.typesafe.ai/introduction/quickstart
+ */
+export declare const JEV_MODEL = "jev-latest";
+export declare const TYPESAFE_SYSTEMONE_URL = "https://api.typesafe.ai/v1/systemone";
+export interface JevChoiceQuestion {
+    readonly type: 'choice';
+    readonly instructions: string;
+    readonly criteria: Readonly<Record<string, string>>;
+}
+export interface JevScoreQuestion {
+    readonly type: 'score';
+    readonly instructions: string;
+    readonly criteria: readonly string[];
+}
+export interface JevNoulQuestion {
+    readonly type: 'noul';
+    readonly instructions: string;
+}
+export type JevQuestion = JevChoiceQuestion | JevScoreQuestion | JevNoulQuestion;
+export interface JevEvaluateInput {
+    readonly state: string | Record<string, unknown> | readonly unknown[];
+    readonly questions: Readonly<Record<string, JevQuestion>>;
+    readonly model?: string;
+}
+export interface JevUsage {
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+}
+export interface JevEvaluateResult {
+    readonly model: string;
+    readonly answers: Readonly<Record<string, unknown>>;
+    readonly usage?: JevUsage;
+}
+export declare class JevConfigError extends Error {
+    constructor(message: string);
+}
+export declare function typesafeApiKey(env?: NodeJS.ProcessEnv): string;
+/**
+ * One System One call. Does not generate text and is not the local snap default.
+ */
+export declare function evaluateJev(input: JevEvaluateInput, options?: {
+    readonly fetchImpl?: typeof fetch;
+    readonly apiKey?: string;
+    readonly url?: string;
+}): Promise<JevEvaluateResult>;
+//# sourceMappingURL=typesafe-jev.d.ts.map

package/dist/llm/providers/typesafe-jev.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typesafe-jev.d.ts","sourceRoot":"","sources":["../../../src/llm/providers/typesafe-jev.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,eAAO,MAAM,SAAS,eAAe,CAAC;AACtC,eAAO,MAAM,sBAAsB,yCAAyC,CAAC;AAE7E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CACtC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAEjF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,OAAO,EAAE,CAAC;IACtE,QAAQ,CAAC,SAAS,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC;CAC3B;AAED,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAED,wBAAgB,cAAc,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAM3E;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,KAAK,EAAE,gBAAgB,EACvB,OAAO,CAAC,EAAE;IAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC/F,OAAO,CAAC,iBAAiB,CAAC,CAsB5B"}

package/dist/llm/providers/typesafe-jev.js

@@ -0,0 +1,50 @@
+/**
+ * TypeSafe Jev — System One decision adapter.
+ *
+ * Not a chat model. Send state plus typed questions. The response is
+ * choices, scores, and noul probabilities. No TypeSafe SDK: one HTTPS POST.
+ * The key is the caller's TYPESAFE_API_KEY. RevealUI does not host one.
+ *
+ * Docs: https://docs.typesafe.ai/introduction/quickstart
+ */
+export const JEV_MODEL = 'jev-latest';
+export const TYPESAFE_SYSTEMONE_URL = 'https://api.typesafe.ai/v1/systemone';
+export class JevConfigError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'JevConfigError';
+    }
+}
+export function typesafeApiKey(env = process.env) {
+    const key = env.TYPESAFE_API_KEY?.trim();
+    if (!key) {
+        throw new JevConfigError('TYPESAFE_API_KEY is required for Jev. RevealUI does not ship one.');
+    }
+    return key;
+}
+/**
+ * One System One call. Does not generate text and is not the local snap default.
+ */
+export async function evaluateJev(input, options) {
+    const fetchImpl = options?.fetchImpl ?? fetch;
+    const response = await fetchImpl(options?.url ?? TYPESAFE_SYSTEMONE_URL, {
+        method: 'POST',
+        headers: {
+            Authorization: `Bearer ${options?.apiKey ?? typesafeApiKey()}`,
+            'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+            state: input.state,
+            model: input.model ?? JEV_MODEL,
+            questions: input.questions,
+        }),
+    });
+    if (!response.ok) {
+        throw new Error(`Jev request failed: HTTP ${response.status}`);
+    }
+    const body = (await response.json());
+    if (!body || typeof body !== 'object' || !body.answers) {
+        throw new Error('Jev response missing answers');
+    }
+    return body;
+}

package/dist/llm/server.d.ts

@@ -10,6 +10,7 @@ export * from './providers/groq.js';
 export * from './providers/inference-snaps.js';
 export * from './providers/ollama.js';
 export * from './providers/openai-compat.js';
+export * from './providers/typesafe-jev.js';
 export * from './resolve.js';
 export * from './workspace-provider-config.js';
 //# sourceMappingURL=server.d.ts.map

package/dist/llm/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/llm/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,aAAa,CAAC;AAE5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAE7C,cAAc,cAAc,CAAC;AAI7B,cAAc,gCAAgC,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/llm/server.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,aAAa,CAAC;AAE5B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,gCAAgC,CAAC;AAC/C,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,6BAA6B,CAAC;AAE5C,cAAc,cAAc,CAAC;AAI7B,cAAc,gCAAgC,CAAC"}

package/dist/llm/server.js

@@ -12,6 +12,7 @@ export * from './providers/groq.js';
 export * from './providers/inference-snaps.js';
 export * from './providers/ollama.js';
 export * from './providers/openai-compat.js';
+export * from './providers/typesafe-jev.js';
 // Export the per-request client resolver (GAP-360 PR-2)
 export * from './resolve.js';
 // Export per-workspace provider registry (used by admin inference-config route

package/dist/orchestration/loop-guard.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Studio LoopGuard client (GAP-362).
+ *
+ * Sock methods on harness.sock are `loop.arm`, `loop.tick`, and `loop.status`.
+ * This client does not call `loop.stop`. `session.end` and `harness.prune`
+ * reap loops on the daemon. Product paths with no daemon keep today's
+ * behavior: a missing socket returns immediately, and a dead or silent socket
+ * fails open inside `timeoutMs` without throwing.
+ *
+ * The daemon owns the no-op counter. Omit `noopLimit` and it applies
+ * `DAEMON_LOOP_NOOP_LIMIT` (3, RevDev `DEFAULT_LOOP_NOOP_LIMIT`). After that
+ * many consecutive `advanced: false` ticks, `loop.tick` returns `stop: true`
+ * and `status: not_advancing`. This module does not keep a second counter.
+ *
+ * `AgentRuntime` stays separate from `runGovernedTask`. Receipts are not
+ * this loop. Do not boot the MCP Hypervisor silent process health loop
+ * without a WIRE mount and a credential owner.
+ */
+/** RevDev `DEFAULT_LOOP_NOOP_LIMIT`. Omitted on arm so the daemon applies it. */
+export declare const DAEMON_LOOP_NOOP_LIMIT = 3;
+/**
+ * Cadence declaration sent on `loop.arm`. RevDev warns on idle intervals
+ * under 60s. Interactive tool loops are not idle polls, so the declaration
+ * stays at this floor. The runtime does not sleep for this long.
+ */
+export declare const DAEMON_LOOP_INTERVAL_MS = 60000;
+/** Bound for a socket that exists but never answers. */
+export declare const DAEMON_LOOP_TIMEOUT_MS = 750;
+/** Used when no Studio session id is cached. Unknown ids are daemon-minted. */
+export declare const PRODUCT_RUNTIME_ACTOR_ID = "revealui-product-runtime";
+export type LoopGuardStatus = 'armed' | 'not_advancing' | 'stopped' | 'unavailable';
+export interface LoopGuardSignal {
+    readonly attached: boolean;
+    readonly status: LoopGuardStatus;
+    readonly signal: string | null;
+}
+export interface LoopGuardTickInput {
+    readonly advanced: boolean;
+    readonly tokensIn?: number;
+    readonly tokensOut?: number;
+    readonly costMicros?: number;
+}
+export interface LoopGuardPort {
+    arm(input: {
+        readonly loopId: string;
+        readonly actorAgentId?: string;
+    }): Promise<LoopGuardSignal>;
+    tick(input: {
+        readonly loopId: string;
+    } & LoopGuardTickInput): Promise<LoopGuardSignal>;
+    /** Read the loop. `{ loop: null }` from the daemon is not attached. */
+    status(loopId: string): Promise<LoopGuardSignal>;
+}
+export interface DaemonLoopGuardConfig {
+    /** Defaults to `REVEALUI_SOCKET` or `~/.local/share/revealui/harness.sock`. */
+    readonly socketPath?: string;
+    /** RPC budget per call when the socket accepts but stays silent. */
+    readonly timeoutMs?: number;
+    /** `loop.arm` cadence declaration. Defaults to {@link DAEMON_LOOP_INTERVAL_MS}. */
+    readonly intervalMs?: number;
+    /**
+     * Sent only when set. Omitted so the daemon keeps {@link DAEMON_LOOP_NOOP_LIMIT}.
+     */
+    readonly noopLimit?: number;
+    /** Overrides the cached Studio session id and the product fallback. */
+    readonly actorAgentId?: string;
+}
+export declare function defaultHarnessSocketPath(): string;
+export declare function isHarnessSocketPresent(socketPath?: string): boolean;
+/**
+ * Studio session id written by harness SessionStart.
+ * The hook process records the parent pid; in-process callers record ppid.
+ */
+export declare function readStudioActorId(): string | null;
+export declare function studioLoopId(taskId: string): string;
+/**
+ * An iteration advances when the model finishes the task or runs at least
+ * one tool that was not a duplicate of an earlier call in the same task.
+ */
+export declare function iterationAdvanced(input: {
+    readonly completed: boolean;
+    readonly newToolExecutions: number;
+}): boolean;
+export declare function createDaemonLoopGuard(config?: DaemonLoopGuardConfig): LoopGuardPort;
+//# sourceMappingURL=loop-guard.d.ts.map

package/dist/orchestration/loop-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop-guard.d.ts","sourceRoot":"","sources":["../../src/orchestration/loop-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAQH,iFAAiF;AACjF,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,wDAAwD;AACxD,eAAO,MAAM,sBAAsB,MAAM,CAAC;AAE1C,+EAA+E;AAC/E,eAAO,MAAM,wBAAwB,6BAA6B,CAAC;AAInE,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,eAAe,GAAG,SAAS,GAAG,aAAa,CAAC;AAEpF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAClG,IAAI,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,GAAG,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACxF,uEAAuE;IACvE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,qBAAqB;IACpC,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,oEAAoE;IACpE,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,mFAAmF;IACnF,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,uEAAuE;IACvE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;CAChC;AAQD,wBAAgB,wBAAwB,IAAI,MAAM,CAIjD;AAED,wBAAgB,sBAAsB,CAAC,UAAU,GAAE,MAAmC,GAAG,OAAO,CAO/F;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,GAAG,IAAI,CAejD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAGnD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC,GAAG,OAAO,CAEV;AAED,wBAAgB,qBAAqB,CAAC,MAAM,GAAE,qBAA0B,GAAG,aAAa,CA6EvF"}

package/dist/orchestration/loop-guard.js

@@ -0,0 +1,252 @@
+/**
+ * Studio LoopGuard client (GAP-362).
+ *
+ * Sock methods on harness.sock are `loop.arm`, `loop.tick`, and `loop.status`.
+ * This client does not call `loop.stop`. `session.end` and `harness.prune`
+ * reap loops on the daemon. Product paths with no daemon keep today's
+ * behavior: a missing socket returns immediately, and a dead or silent socket
+ * fails open inside `timeoutMs` without throwing.
+ *
+ * The daemon owns the no-op counter. Omit `noopLimit` and it applies
+ * `DAEMON_LOOP_NOOP_LIMIT` (3, RevDev `DEFAULT_LOOP_NOOP_LIMIT`). After that
+ * many consecutive `advanced: false` ticks, `loop.tick` returns `stop: true`
+ * and `status: not_advancing`. This module does not keep a second counter.
+ *
+ * `AgentRuntime` stays separate from `runGovernedTask`. Receipts are not
+ * this loop. Do not boot the MCP Hypervisor silent process health loop
+ * without a WIRE mount and a credential owner.
+ */
+import { randomUUID } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { createConnection } from 'node:net';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+/** RevDev `DEFAULT_LOOP_NOOP_LIMIT`. Omitted on arm so the daemon applies it. */
+export const DAEMON_LOOP_NOOP_LIMIT = 3;
+/**
+ * Cadence declaration sent on `loop.arm`. RevDev warns on idle intervals
+ * under 60s. Interactive tool loops are not idle polls, so the declaration
+ * stays at this floor. The runtime does not sleep for this long.
+ */
+export const DAEMON_LOOP_INTERVAL_MS = 60_000;
+/** Bound for a socket that exists but never answers. */
+export const DAEMON_LOOP_TIMEOUT_MS = 750;
+/** Used when no Studio session id is cached. Unknown ids are daemon-minted. */
+export const PRODUCT_RUNTIME_ACTOR_ID = 'revealui-product-runtime';
+const ACTOR_ID_MAX = 256;
+const UNAVAILABLE = {
+    attached: false,
+    status: 'unavailable',
+    signal: null,
+};
+export function defaultHarnessSocketPath() {
+    return (process.env.REVEALUI_SOCKET ?? join(homedir(), '.local', 'share', 'revealui', 'harness.sock'));
+}
+export function isHarnessSocketPresent(socketPath = defaultHarnessSocketPath()) {
+    try {
+        if (!existsSync(socketPath))
+            return false;
+        return Boolean(statSync(socketPath));
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Studio session id written by harness SessionStart.
+ * The hook process records the parent pid; in-process callers record ppid.
+ */
+export function readStudioActorId() {
+    const dir = process.env.REVDEV_DAEMON_SESSION_DIR ??
+        join(homedir(), '.local', 'share', 'revealui', 'daemon-sessions');
+    const keys = [process.pid, process.ppid];
+    for (const key of keys) {
+        try {
+            const raw = readFileSync(join(dir, `${key}.id`), 'utf8');
+            const id = usableActorId(raw);
+            if (id)
+                return id;
+        }
+        catch {
+            /* absent */
+        }
+    }
+    return null;
+}
+export function studioLoopId(taskId) {
+    const safe = taskId.length > 120 ? taskId.slice(0, 120) : taskId;
+    return `agent-runtime:${safe}:${randomUUID()}`;
+}
+/**
+ * An iteration advances when the model finishes the task or runs at least
+ * one tool that was not a duplicate of an earlier call in the same task.
+ */
+export function iterationAdvanced(input) {
+    return input.completed || input.newToolExecutions > 0;
+}
+export function createDaemonLoopGuard(config = {}) {
+    const socketPath = config.socketPath ?? defaultHarnessSocketPath();
+    const timeoutMs = config.timeoutMs ?? DAEMON_LOOP_TIMEOUT_MS;
+    const intervalMs = config.intervalMs ?? DAEMON_LOOP_INTERVAL_MS;
+    const noopLimit = config.noopLimit;
+    let attached = false;
+    let disabled = false;
+    let actorAgentId = usableActorId(config.actorAgentId ?? '') ?? PRODUCT_RUNTIME_ACTOR_ID;
+    async function call(method, params) {
+        return rpcCall(socketPath, method, params, timeoutMs);
+    }
+    return {
+        async arm(input) {
+            if (disabled)
+                return UNAVAILABLE;
+            const explicit = usableActorId(input.actorAgentId ?? config.actorAgentId ?? '');
+            actorAgentId = explicit ?? readStudioActorId() ?? PRODUCT_RUNTIME_ACTOR_ID;
+            if (!isHarnessSocketPresent(socketPath)) {
+                disabled = true;
+                return UNAVAILABLE;
+            }
+            const params = {
+                loopId: input.loopId,
+                intervalMs,
+                actorAgentId,
+            };
+            if (typeof noopLimit === 'number' && noopLimit > 0) {
+                params.noopLimit = Math.floor(noopLimit);
+            }
+            try {
+                const result = await call('loop.arm', params);
+                attached = true;
+                return signalFromResult(result);
+            }
+            catch {
+                disabled = true;
+                attached = false;
+                return UNAVAILABLE;
+            }
+        },
+        async tick(input) {
+            if (!attached || disabled)
+                return UNAVAILABLE;
+            const params = {
+                loopId: input.loopId,
+                advanced: input.advanced,
+                actorAgentId,
+            };
+            if (typeof input.tokensIn === 'number' && input.tokensIn > 0) {
+                params.tokensIn = Math.floor(input.tokensIn);
+            }
+            if (typeof input.tokensOut === 'number' && input.tokensOut > 0) {
+                params.tokensOut = Math.floor(input.tokensOut);
+            }
+            if (typeof input.costMicros === 'number' && input.costMicros > 0) {
+                params.costMicros = Math.floor(input.costMicros);
+            }
+            try {
+                const result = await call('loop.tick', params);
+                return signalFromResult(result);
+            }
+            catch {
+                disabled = true;
+                return UNAVAILABLE;
+            }
+        },
+        async status(loopId) {
+            if (!attached || disabled)
+                return UNAVAILABLE;
+            try {
+                const result = await call('loop.status', { loopId, actorAgentId });
+                return signalFromResult(result);
+            }
+            catch {
+                disabled = true;
+                return UNAVAILABLE;
+            }
+        },
+    };
+}
+function usableActorId(raw) {
+    const id = raw.trim();
+    if (id.length === 0 || id.length > ACTOR_ID_MAX)
+        return null;
+    if (id.includes('/') || id.includes('\\') || id.includes('\0'))
+        return null;
+    return id;
+}
+function signalFromResult(result) {
+    if (!result || typeof result !== 'object') {
+        return { attached: true, status: 'armed', signal: null };
+    }
+    const record = result;
+    if (record.loop == null) {
+        return UNAVAILABLE;
+    }
+    if (typeof record.loop !== 'object') {
+        return { attached: true, status: 'armed', signal: null };
+    }
+    const statusRaw = record.loop.status;
+    const signalRaw = record.loop.lastSignal;
+    const signal = typeof signalRaw === 'string' ? signalRaw : null;
+    if (record.stop === true || statusRaw === 'not_advancing') {
+        return {
+            attached: true,
+            status: 'not_advancing',
+            signal: signal ?? 'loop not advancing',
+        };
+    }
+    if (statusRaw === 'stopped' || statusRaw === 'armed') {
+        return { attached: true, status: statusRaw, signal };
+    }
+    return { attached: true, status: 'armed', signal };
+}
+function rpcCall(socketPath, method, params, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const socket = createConnection(socketPath);
+        let buffer = '';
+        let settled = false;
+        let timer;
+        const finish = (err, value) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer)
+                clearTimeout(timer);
+            socket.destroy();
+            if (err)
+                reject(err);
+            else
+                resolve(value);
+        };
+        timer = setTimeout(() => {
+            finish(new Error(`loop guard RPC timeout after ${timeoutMs}ms`));
+        }, timeoutMs);
+        socket.on('connect', () => {
+            const frame = JSON.stringify({ jsonrpc: '2.0', id: 1, method, params });
+            socket.write(`${frame}\n`);
+        });
+        socket.on('data', (chunk) => {
+            buffer += chunk.toString();
+            const lines = buffer.split('\n');
+            buffer = lines.pop() ?? '';
+            for (const line of lines) {
+                if (!line.trim())
+                    continue;
+                try {
+                    const resp = JSON.parse(line);
+                    if (resp.error) {
+                        finish(new Error(resp.error.message ?? 'loop guard RPC error'));
+                    }
+                    else {
+                        finish(null, resp.result);
+                    }
+                }
+                catch (err) {
+                    finish(err instanceof Error ? err : new Error(String(err)));
+                }
+                return;
+            }
+        });
+        socket.on('error', (err) => {
+            finish(err);
+        });
+    });
+}

package/dist/orchestration/runtime.d.ts

@@ -1,7 +1,18 @@
 /**
  * Agent Runtime
  *
- * Executes agent tasks with tool execution, memory management, and error handling
+ * Interactive tool loop (`executeTask`). Intentionally separate from
+ * `runGovernedTask` (governed receipts in `@revealui/apify-actor-governed-run`):
+ * receipts need an ordered action log and hard step caps; this runtime stays
+ * an open loop. Do not merge them.
+ *
+ * When the RevDev harness socket is reachable, each task arms Studio LoopGuard
+ * and ticks once per model iteration (`loop.arm`, `loop.tick`, `loop.status`).
+ * This runtime does not call `loop.stop`. `session.end` and `harness.prune`
+ * reap the loop. No daemon means no tick and no throw.
+ *
+ * Do not boot the MCP Hypervisor silent process health loop without a WIRE
+ * mount and a credential owner.
  */
 import type { LLMClient } from '../llm/client.js';
 import type { ReasoningEffort } from '../llm/providers/base.js';
@@ -10,6 +21,9 @@ import type { ApprovalCallback } from '../tools/base.js';
 import { type McpClientLike } from '../tools/mcp-adapter.js';
 import type { McpToolCallEvent } from '../tools/mcp-events.js';
 import type { Agent, AgentResult, Task } from './agent.js';
+import { type LoopGuardPort, type LoopGuardTickInput } from './loop-guard.js';
+export type { LoopGuardPort, LoopGuardSignal, LoopGuardTickInput } from './loop-guard.js';
+export { createDaemonLoopGuard, DAEMON_LOOP_INTERVAL_MS, DAEMON_LOOP_NOOP_LIMIT, DAEMON_LOOP_TIMEOUT_MS, iterationAdvanced, PRODUCT_RUNTIME_ACTOR_ID, studioLoopId, } from './loop-guard.js';
 /**
  * Reasoning-depth hint for a task. Alias of the neutral `ReasoningEffort` — the agnostic
  * Reasoner port's control vocabulary. Mapping a level to a provider's native control
@@ -89,9 +103,19 @@ export interface RuntimeConfig {
      * policy (e.g., from AgentSecuritySchema.requiresHumanApproval).
      */
     alwaysRequireApproval?: string[];
+    /**
+     * Studio LoopGuard (GAP-362). Default: `loop.arm`, `loop.tick`, and
+     * `loop.status` on the RevDev harness socket when it is reachable.
+     * This runtime does not call `loop.stop`. `session.end` and `harness.prune`
+     * reap the loop. Missing socket, connect failure, and RPC timeout leave
+     * the task on the unwired path (no throw). Pass `false` to skip the daemon
+     * even when Studio is attached. `runGovernedTask` does not use this port.
+     */
+    loopGuard?: LoopGuardPort | false;
 }
 export declare class AgentRuntime {
     protected config: RuntimeConfig;
+    private readonly loopGuard;
     private taskQueue;
     private executingTasks;
     private isShuttingDown;
@@ -101,6 +125,16 @@ export declare class AgentRuntime {
      */
     executeTask(agent: Agent, task: Task, llmClient: LLMClient): Promise<AgentResult>;
     private runTask;
+    /**
+     * Arm LoopGuard for this task when Studio's daemon answers.
+     * Returns null when the daemon is absent or the call fails open.
+     */
+    protected openStudioLoop(taskId: string): Promise<string | null>;
+    /**
+     * Report one model iteration. A non-null return is the daemon stop signal
+     * (`not_advancing` after the daemon no-op limit, default 3).
+     */
+    protected tickStudioLoop(loopId: string | null, tick: LoopGuardTickInput): Promise<string | null>;
     /**
      * Add task to queue
      */

package/dist/orchestration/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/orchestration/runtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAW,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAGzE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,+CAA+C,CAAC;AACxF,OAAO,KAAK,EAAE,gBAAgB,EAAoB,MAAM,kBAAkB,CAAC;AAE3E,OAAO,EAA4B,KAAK,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACvF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAE/D,OAAO,KAAK,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAE3D;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,eAAe,CAAC;AAE5C,MAAM,WAAW,aAAa;IAC5B,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,EAAE,aAAa,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,aAAa,CAAA;KAAE,CAAC,CAAC;IACpE;;;;OAIG;IACH,WAAW,CAAC,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChE;;;;OAIG;IACH,aAAa,CAAC,EAAE,kBAAkB,CAAC;IACnC;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,gCAAgC,EAAE,SAAS,CAAC;IAC/D;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;CAClC;AAED,qBAAa,YAAY;IACvB,SAAS,CAAC,MAAM,EAAE,aAAa,CAAC;IAChC,OAAO,CAAC,SAAS,CAAc;IAC/B,OAAO,CAAC,cAAc,CAAgD;IACtE,OAAO,CAAC,cAAc,CAAS;gBAEnB,MAAM,GAAE,aAAkB;IA0BtC;;OAEG;IACG,WAAW,CAAC,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,CAAC;YAqBzE,OAAO;IA6OrB;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAI7B;;OAEG;IACG,YAAY,CAAC,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,SAAS,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IAc9E;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA+B9B;;OAEG;IACH,SAAS,IAAI;QACX,cAAc,EAAE,OAAO,CAAC;QACxB,WAAW,EAAE,MAAM,CAAC;QACpB,cAAc,EAAE,MAAM,CAAC;KACxB;CAOF"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../../src/orchestration/runtime.ts"],"names":[],"mappings":"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"}

package/dist/orchestration/runtime.js

@@ -1,7 +1,18 @@
 /**
  * Agent Runtime
  *
- * Executes agent tasks with tool execution, memory management, and error handling
+ * Interactive tool loop (`executeTask`). Intentionally separate from
+ * `runGovernedTask` (governed receipts in `@revealui/apify-actor-governed-run`):
+ * receipts need an ordered action log and hard step caps; this runtime stays
+ * an open loop. Do not merge them.
+ *
+ * When the RevDev harness socket is reachable, each task arms Studio LoopGuard
+ * and ticks once per model iteration (`loop.arm`, `loop.tick`, `loop.status`).
+ * This runtime does not call `loop.stop`. `session.end` and `harness.prune`
+ * reap the loop. No daemon means no tick and no throw.
+ *
+ * Do not boot the MCP Hypervisor silent process health loop without a WIRE
+ * mount and a credential owner.
  */
 import { registerCleanupHandler } from '@revealui/core/monitoring';
 import { estimateCost } from '../llm/token-counter.js';
@@ -9,12 +20,17 @@ import { toolParametersToJsonSchema } from '../llm/tool-json-schema.js';
 import { ToolCallDeduplicator } from '../tools/deduplicator.js';
 import { createToolsFromMcpClient } from '../tools/mcp-adapter.js';
 import { createWebSearchTool } from '../tools/web/duck-duck-go.js';
+import { createDaemonLoopGuard, iterationAdvanced, studioLoopId, } from './loop-guard.js';
+export { createDaemonLoopGuard, DAEMON_LOOP_INTERVAL_MS, DAEMON_LOOP_NOOP_LIMIT, DAEMON_LOOP_TIMEOUT_MS, iterationAdvanced, PRODUCT_RUNTIME_ACTOR_ID, studioLoopId, } from './loop-guard.js';
 export class AgentRuntime {
     config;
+    loopGuard;
     taskQueue = [];
     executingTasks = new Map();
     isShuttingDown = false;
     constructor(config = {}) {
+        this.loopGuard =
+            config.loopGuard === false ? null : (config.loopGuard ?? createDaemonLoopGuard());
         this.config = {
             maxIterations: config.maxIterations ?? 10,
             timeout: config.timeout ?? 60000, // 60 seconds
@@ -60,6 +76,7 @@ export class AgentRuntime {
         let iterations = 0;
         let totalTokens = 0;
         let totalCostUsd = 0;
+        const loopId = await this.openStudioLoop(task.id);
         // Merge MCP-discovered tools into the agent's tool set via `McpClient`.
         const mcpTools = [];
         const onToolAudit = this.config.onToolAudit;
@@ -138,12 +155,9 @@ export class AgentRuntime {
                 const iterationTokens = response.usage?.totalTokens ?? 0;
                 totalTokens += iterationTokens;
                 const model = this.config.model;
-                if (model && iterationTokens > 0) {
-                    const inputTokens = response.usage?.promptTokens ?? Math.floor(iterationTokens * 0.7);
-                    const outputTokens = response.usage?.completionTokens ?? iterationTokens - inputTokens;
-                    totalCostUsd +=
-                        estimateCost(inputTokens, model, 'input').estimatedCostUsd +
-                            estimateCost(outputTokens, model, 'output').estimatedCostUsd;
+                const spend = iterationSpend(response, model, iterationTokens);
+                if (spend.costUsd > 0) {
+                    totalCostUsd += spend.costUsd;
                 }
                 // Add assistant response to messages
                 messages.push({
@@ -153,6 +167,22 @@ export class AgentRuntime {
                 });
                 // If no tool calls, task is complete
                 if (!response.toolCalls || response.toolCalls.length === 0) {
+                    const stopReason = await this.tickStudioLoop(loopId, {
+                        advanced: iterationAdvanced({ completed: true, newToolExecutions: 0 }),
+                        ...spend.tick,
+                    });
+                    if (stopReason) {
+                        return {
+                            success: false,
+                            error: stopReason,
+                            toolResults,
+                            metadata: {
+                                executionTime: Date.now() - startTime,
+                                tokensUsed: totalTokens,
+                                cost: totalCostUsd,
+                            },
+                        };
+                    }
                     return {
                         success: true,
                         output: response.content,
@@ -165,6 +195,7 @@ export class AgentRuntime {
                     };
                 }
                 // Execute tool calls
+                let newToolExecutions = 0;
                 for (const toolCall of response.toolCalls) {
                     const tool = allTools.find((t) => t.name === toolCall.function.name);
                     if (!tool) {
@@ -206,6 +237,7 @@ export class AgentRuntime {
                                         ? `Tool "${tool.label ?? tool.name}" denied: ${approval.reason}`
                                         : `Tool "${tool.label ?? tool.name}" was denied by the user.`,
                                 };
+                                newToolExecutions += 1;
                                 toolResults.push(denied);
                                 messages.push({
                                     role: 'tool',
@@ -220,8 +252,10 @@ export class AgentRuntime {
                             ? deduplicator.getResult(tool.name, params)
                             : undefined;
                         const result = cached ?? (await tool.execute(params));
-                        if (!cached)
+                        if (!cached) {
                             deduplicator.record(tool.name, params, result);
+                            newToolExecutions += 1;
+                        }
                         toolResults.push(result);
                         // Add tool result to messages.
                         // Use result.content (LLM-optimized summary) when available;
@@ -233,12 +267,29 @@ export class AgentRuntime {
                         });
                     }
                     catch (error) {
+                        newToolExecutions += 1;
                         toolResults.push({
                             success: false,
                             error: error instanceof Error ? error.message : String(error),
                         });
                     }
                 }
+                const stopReason = await this.tickStudioLoop(loopId, {
+                    advanced: iterationAdvanced({ completed: false, newToolExecutions }),
+                    ...spend.tick,
+                });
+                if (stopReason) {
+                    return {
+                        success: false,
+                        error: stopReason,
+                        toolResults,
+                        metadata: {
+                            executionTime: Date.now() - startTime,
+                            tokensUsed: totalTokens,
+                            cost: totalCostUsd,
+                        },
+                    };
+                }
             }
             return {
                 success: false,
@@ -264,6 +315,42 @@ export class AgentRuntime {
             };
         }
     }
+    /**
+     * Arm LoopGuard for this task when Studio's daemon answers.
+     * Returns null when the daemon is absent or the call fails open.
+     */
+    async openStudioLoop(taskId) {
+        if (!this.loopGuard)
+            return null;
+        const loopId = studioLoopId(taskId);
+        try {
+            const signal = await this.loopGuard.arm({ loopId });
+            return signal.attached ? loopId : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Report one model iteration. A non-null return is the daemon stop signal
+     * (`not_advancing` after the daemon no-op limit, default 3).
+     */
+    async tickStudioLoop(loopId, tick) {
+        if (!(loopId && this.loopGuard))
+            return null;
+        try {
+            const signal = await this.loopGuard.tick({ loopId, ...tick });
+            if (!signal.attached)
+                return null;
+            if (signal.status === 'not_advancing') {
+                return signal.signal ?? 'loop not advancing';
+            }
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * Add task to queue
      */
@@ -319,3 +406,23 @@ export class AgentRuntime {
         };
     }
 }
+function iterationSpend(response, model, iterationTokens) {
+    const tokensIn = response.usage?.promptTokens ?? (iterationTokens > 0 ? Math.floor(iterationTokens * 0.7) : 0);
+    const tokensOut = response.usage?.completionTokens ??
+        (iterationTokens > 0 ? Math.max(0, iterationTokens - tokensIn) : 0);
+    let costUsd = 0;
+    if (model && iterationTokens > 0) {
+        costUsd =
+            estimateCost(tokensIn, model, 'input').estimatedCostUsd +
+                estimateCost(tokensOut, model, 'output').estimatedCostUsd;
+    }
+    const costMicros = costUsd > 0 ? Math.round(costUsd * 1_000_000) : 0;
+    return {
+        costUsd,
+        tick: {
+            ...(tokensIn > 0 ? { tokensIn } : {}),
+            ...(tokensOut > 0 ? { tokensOut } : {}),
+            ...(costMicros > 0 ? { costMicros } : {}),
+        },
+    };
+}

package/dist/orchestration/streaming-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"streaming-runtime.d.ts","sourceRoot":"","sources":["../../src/orchestration/streaming-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EACA,MAAM,GACN,iBAAiB,GACjB,kBAAkB,GAClB,OAAO,GACP,MAAM,GACN,cAAc,GACd,kBAAkB,GAClB,qBAAqB,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,uDAAuD;IACvD,WAAW,CAAC,EAAE;QACZ,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,OAAO,CAAC;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,MAAM,GAAE,aAAkB;IAItC;;;OAGG;IACI,UAAU,CACf,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,SAAS,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,cAAc,CAAC,gBAAgB,CAAC;CAsLpC"}
+{"version":3,"file":"streaming-runtime.d.ts","sourceRoot":"","sources":["../../src/orchestration/streaming-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAE9C,OAAO,EAAE,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAEhE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EACA,MAAM,GACN,iBAAiB,GACjB,kBAAkB,GAClB,OAAO,GACP,MAAM,GACN,cAAc,GACd,kBAAkB,GAClB,qBAAqB,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IAC/C,UAAU,CAAC,EAAE,UAAU,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE;QACT,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,aAAa,CAAC,EAAE,MAAM,CAAC;KACxB,CAAC;IACF;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE;QACT,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,CAAC;QACrB,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF,uDAAuD;IACvD,WAAW,CAAC,EAAE;QACZ,aAAa,EAAE,MAAM,CAAC;QACtB,eAAe,EAAE,OAAO,CAAC;QACzB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;CACH;AAED,qBAAa,qBAAsB,SAAQ,YAAY;gBACzC,MAAM,GAAE,aAAkB;IAItC;;;OAGG;IACI,UAAU,CACf,KAAK,EAAE,KAAK,EACZ,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,SAAS,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,cAAc,CAAC,gBAAgB,CAAC;CA0MpC"}

package/dist/orchestration/streaming-runtime.js

@@ -10,6 +10,7 @@
 import { compressToolResult } from '../inference/tool-result-compressor.js';
 import { toolParametersToJsonSchema } from '../llm/tool-json-schema.js';
 import { ToolCallDeduplicator } from '../tools/deduplicator.js';
+import { iterationAdvanced } from './loop-guard.js';
 import { AgentRuntime } from './runtime.js';
 export class StreamingAgentRuntime extends AgentRuntime {
     constructor(config = {}) {
@@ -43,6 +44,7 @@ export class StreamingAgentRuntime extends AgentRuntime {
                 content: task.description,
             },
         ];
+        const loopId = await this.openStudioLoop(task.id);
         try {
             while (iterations < maxIterations) {
                 iterations++;
@@ -96,6 +98,13 @@ export class StreamingAgentRuntime extends AgentRuntime {
                 }
                 // If no tool calls, task is complete
                 if (pendingToolCalls.length === 0) {
+                    const stopReason = await this.tickStudioLoop(loopId, {
+                        advanced: iterationAdvanced({ completed: true, newToolExecutions: 0 }),
+                    });
+                    if (stopReason) {
+                        yield { type: 'error', error: stopReason };
+                        return;
+                    }
                     yield {
                         type: 'done',
                         content: accumulatedContent,
@@ -109,7 +118,9 @@ export class StreamingAgentRuntime extends AgentRuntime {
                     content: accumulatedContent,
                     toolCalls: pendingToolCalls,
                 });
-                // Execute all tool calls in this response
+                // Execute all tool calls in this response.
+                // Stream chunks do not carry provider usage, so these ticks omit spend.
+                let newToolExecutions = 0;
                 for (const tc of pendingToolCalls) {
                     yield { type: 'tool_call_start', toolCall: { name: tc.name, arguments: tc.arguments } };
                     const tool = agent.tools.find((t) => t.name === tc.name);
@@ -146,6 +157,7 @@ export class StreamingAgentRuntime extends AgentRuntime {
                     try {
                         const result = await tool.execute(params);
                         deduplicator.record(tc.name, params, result);
+                        newToolExecutions += 1;
                         toolResults.push(result);
                         yield { type: 'tool_call_result', toolResult: result };
                         messages.push({
@@ -155,6 +167,7 @@ export class StreamingAgentRuntime extends AgentRuntime {
                         });
                     }
                     catch (toolError) {
+                        newToolExecutions += 1;
                         const result = {
                             success: false,
                             error: toolError instanceof Error ? toolError.message : String(toolError),
@@ -168,6 +181,13 @@ export class StreamingAgentRuntime extends AgentRuntime {
                         });
                     }
                 }
+                const stopReason = await this.tickStudioLoop(loopId, {
+                    advanced: iterationAdvanced({ completed: false, newToolExecutions }),
+                });
+                if (stopReason) {
+                    yield { type: 'error', error: stopReason };
+                    return;
+                }
             }
             yield { type: 'error', error: 'Maximum iterations reached' };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revealui/ai",
-  "version": "1.0.7",
+  "version": "1.2.2",
   "description": "AI runtime for agent-driven products — agents, memory, LLM providers (Inference Snaps, Ollama, OpenAI-compatible), tools, and orchestration. Anthropic-SDK-free.",
   "keywords": [
     "agent",
@@ -25,9 +25,9 @@
   "dependencies": {
     "lru-cache": "^11.5.1",
     "zod": "^4.4.3",
-    "@revealui/contracts": "0.11.0",
-    "@revealui/core": "0.14.7",
-    "@revealui/db": "0.10.3",
+    "@revealui/contracts": "0.13.2",
+    "@revealui/core": "0.15.3",
+    "@revealui/db": "0.12.1",
     "@revealui/resilience": "0.2.4"
   },
   "devDependencies": {