@rivus/runtime 0.16.2

package/dist/chunks/rivus-runtime-tool.d.ts

@@ -0,0 +1,386 @@
+import { Pt as AgentRunId, it as AgentMemoryInvocationIdentity, rt as AgentInvocationOrigin } from "./agent-loop.js";
+import { Effect } from "effect";
+
+//#region src/core/application/agent-execution/contracts/model-runtime.d.ts
+/**
+ * Runtime-owned model contracts. These describe the actual model binding and
+ * the validate/activate/restore operations plus the bounded paid-call budget
+ * that real Pi resources need. Gateway policy (persistent requests,
+ * authorization, budget reservation/settlement, recovery) maps onto these
+ * capabilities but does not live here.
+ */
+interface ModelReference {
+  readonly model: string;
+  readonly provider: string;
+}
+interface ModelBinding extends ModelReference {
+  /** Provider/adapter binding revision used to invalidate stale validation. */
+  readonly bindingRevision: string;
+}
+interface ModelChangeRuntimeContext {
+  readonly baseline: ModelBinding;
+  readonly bindingRevision: string;
+  readonly target: ModelReference;
+}
+type ModelChangePaidCallKind = "activation" | "restore" | "validation";
+/**
+ * Minimal Runtime budget reservation shape. Pi only needs the reservation id
+ * (for settlement tracking) and the allocated max output tokens (for the
+ * provider call and failure settlement). Request identity, kind, timestamps
+ * and paid-request counts are Gateway policy and do not cross this boundary.
+ */
+interface ModelChangeBudgetReservation {
+  readonly id: string;
+  readonly maxOutputTokens: number;
+}
+interface ModelChangeExecutionBudget {
+  /** Fixed deadline for every paid call in this accepted request. */
+  readonly deadlineAt: string;
+  reservePaidCall(input: {
+    readonly kind: ModelChangePaidCallKind;
+    readonly maxOutputTokens?: number;
+  }): Effect.Effect<{
+    readonly reservation: ModelChangeBudgetReservation;
+    readonly settle: (input: {
+      readonly outcome: "known" | "unknown";
+      readonly outputTokens: number;
+    }) => Effect.Effect<unknown, unknown>;
+  }, unknown>;
+}
+interface ModelChangeValidationResult {
+  readonly evidence: Readonly<Record<string, unknown>>;
+  readonly model: ModelBinding;
+  readonly outputTokens: number;
+  readonly passed: true;
+}
+interface ModelChangeActivationResult {
+  readonly evidence: Readonly<Record<string, unknown>>;
+  readonly outputTokens: number;
+  readonly switched: true;
+}
+interface ModelChangeRestoreResult {
+  readonly evidence: Readonly<Record<string, unknown>>;
+  readonly restored: true;
+}
+interface ModelChangeRuntimePort {
+  activate(input: {
+    readonly beforeApply?: () => Effect.Effect<void, unknown>;
+    readonly context: ModelChangeRuntimeContext;
+    readonly budget: ModelChangeExecutionBudget;
+    readonly validation: ModelChangeValidationResult;
+  }): Effect.Effect<ModelChangeActivationResult, unknown>;
+  current?(): Effect.Effect<ModelBinding | undefined, unknown>;
+  drain(input: ModelChangeRuntimeContext & {
+    readonly deadlineAt: string;
+  }): Effect.Effect<void, unknown>;
+  releasePrevious(input: ModelChangeRuntimeContext & {
+    readonly deadlineAt: string;
+  }): Effect.Effect<void, unknown>;
+  restore(input: {
+    readonly budget: ModelChangeExecutionBudget;
+    readonly context: ModelChangeRuntimeContext;
+    readonly reason: string;
+  }): Effect.Effect<ModelChangeRestoreResult, unknown>;
+  validate(input: {
+    readonly budget: ModelChangeExecutionBudget;
+    readonly context: ModelChangeRuntimeContext;
+  }): Effect.Effect<ModelChangeValidationResult, unknown>;
+}
+//#endregion
+//#region src/core/application/agent-execution/contracts/rivus-skill.d.ts
+interface RivusSkillDescriptor {
+  readonly id: string;
+  readonly version: string;
+  readonly digest: string;
+  readonly title: string;
+  readonly content: string;
+}
+interface RegisteredRivusSkill extends RivusSkillDescriptor {
+  readonly pluginId: string;
+}
+interface RivusSkillGrantSet {
+  readonly skillIds: ReadonlyArray<string>;
+  readonly revision: string;
+}
+//#endregion
+//#region src/core/application/agent-execution/contracts/run-admission.d.ts
+/**
+ * Runtime-owned run admission mechanism. The execution application owns the
+ * active-run counter and the fence that lets a model change drain in-flight
+ * work. Waiting Runs are parked outside the active count, so a drain can close
+ * admission and wait only for work that actually started.
+ *
+ * This interface carries no model-change request identity or request deadline.
+ * The Gateway coordinator wraps it with the {@link ModelChangeBoundaryPort}
+ * protocol (request id, drain deadline, resume semantics) in the deployment
+ * boundary.
+ */
+interface RunAdmission {
+  /** Acquire admission for one concrete Run before resolving a session/model. */
+  acquireRun(input?: {
+    readonly deadlineAt?: string;
+    readonly signal?: AbortSignal;
+  }): Effect.Effect<RunAdmissionLease, unknown>;
+  /** Synchronously close admission; existing leases continue to drain. */
+  fence(): void;
+  /** Effect that succeeds when the active run count reaches zero. */
+  whenDrained(): Effect.Effect<void, unknown>;
+  /** Reopen admission after a model change. Releases waiting runs. */
+  reopen(): void;
+  readonly activeRunCount: () => number;
+  readonly admissionOpen: () => boolean;
+}
+interface RunAdmissionLease {
+  /** Release exactly one active Run. Releasing twice is harmless. */
+  readonly release: () => void;
+}
+interface RunAdmissionOptions {
+  readonly clock: ModelChangeClock;
+}
+interface ModelChangeClock {
+  now(): string;
+}
+declare class ModelChangeBoundaryDeadlineError extends Error {
+  readonly name = "ModelChangeBoundaryDeadlineError";
+}
+//#endregion
+//#region src/core/application/tool-execution/contracts/rivus-tool.d.ts
+type RivusMemoryScope = "conversation" | "agent-private" | "project" | "shared-user-profile";
+type RivusToolRisk = "observe" | "mutate" | "irreversible" | "host-control";
+type RivusToolIdempotency = "none" | "supported" | "required";
+declare class RivusToolInputRejected extends Error {
+  readonly name: string;
+}
+interface RivusToolExecutor {
+  execute(input: unknown, context: RivusToolExecutionContext): unknown;
+}
+interface RivusToolExecutionOrigin {
+  readonly endpointId: string;
+  readonly tenantKey: string;
+  readonly conversationId?: string;
+  readonly allowedActorOpenIds: ReadonlyArray<string>;
+}
+interface RivusToolExecutionContext {
+  readonly agentId: string;
+  readonly instanceId: string;
+  readonly memory?: RivusMemoryAuthority;
+  readonly runId: string;
+  readonly callId: string;
+  readonly operationId?: string;
+  readonly policyEpoch: number;
+  readonly toolId: string;
+  readonly toolVersion: string;
+  readonly sessionKey: string;
+  readonly origin?: RivusToolExecutionOrigin;
+  readonly sourceMessageId?: string;
+}
+interface RivusMemoryAuthority {
+  readonly audience: "group" | "private";
+  readonly conversationId?: string;
+  readonly projectId?: string;
+  readonly scopes: ReadonlyArray<RivusMemoryScope>;
+  readonly subjectId: string;
+  readonly tenantId: string;
+}
+interface RivusToolFactoryContext {
+  readonly toolId: string;
+  readonly toolVersion: string;
+}
+interface RivusToolDescriptor {
+  readonly id: string;
+  readonly version: string;
+  readonly digest: string;
+  readonly description: string;
+  readonly inputSchema: unknown;
+  readonly risk: RivusToolRisk;
+  readonly idempotency: RivusToolIdempotency;
+  readonly createExecutor: (context: RivusToolFactoryContext) => RivusToolExecutor;
+}
+interface RivusHostToolDescriptor extends RivusToolDescriptor {
+  readonly replayCompleted?: (input: unknown, completedResult: unknown, context: RivusToolExecutionContext) => unknown;
+}
+interface RegisteredRivusTool extends RivusToolDescriptor {
+  readonly pluginId: string;
+}
+interface RivusResolvedToolDescriptor {
+  readonly id: string;
+  readonly version: string;
+  readonly digest: string;
+  readonly description: string;
+  readonly inputSchema: unknown;
+  readonly risk: RivusToolRisk;
+  readonly idempotency: RivusToolIdempotency;
+  readonly pluginId: string;
+}
+interface RivusToolGrantSet {
+  readonly toolIds: ReadonlyArray<string>;
+  readonly revision: string;
+}
+interface RivusToolGrantSetOperations {
+  narrow(parent: RivusToolGrantSet, restrictions: ReadonlyArray<ReadonlyArray<string>>): RivusToolGrantSet;
+  intersect(sets: ReadonlyArray<ReadonlyArray<string>>): RivusToolGrantSet;
+}
+//#endregion
+//#region src/core/application/agent-execution/observation/agent-model-content-observer.d.ts
+interface AgentModelInputObservation {
+  readonly input: unknown;
+  readonly modelCallId: string;
+  readonly runId: AgentRunId;
+}
+interface AgentModelOutputObservation {
+  readonly modelCallId: string;
+  readonly output: unknown;
+  readonly runId: AgentRunId;
+}
+interface AgentModelContentObserver {
+  observeInput(observation: AgentModelInputObservation): void;
+  observeOutput(observation: AgentModelOutputObservation): void;
+}
+//#endregion
+//#region src/core/application/agent-execution/invocation/agent-invocation-identity.d.ts
+interface NormalizedAgentInvocation {
+  readonly allowedActorOpenIds: ReadonlyArray<string>;
+  readonly conversationId?: string;
+  readonly endpointId: string;
+  readonly memory?: AgentMemoryInvocationIdentity;
+  readonly sourceMessageId: string;
+  readonly tenantKey: string;
+}
+/**
+ * Background-session conversationId is captured only from the explicit origin
+ * field; when absent it must not fall back to memory, which would expand the
+ * association scope beyond the reviewed binding.
+ */
+declare function normalizeAgentInvocation(origin: AgentInvocationOrigin): NormalizedAgentInvocation;
+//#endregion
+//#region src/core/application/tool-execution/authority/invocation-authority-registry.d.ts
+type InvocationMemoryScope = "conversation" | "agent-private" | "project" | "shared-user-profile";
+interface InvocationMemoryAuthority {
+  readonly audience: "group" | "private";
+  readonly conversationId?: string;
+  readonly projectId?: string;
+  readonly scopes: ReadonlyArray<InvocationMemoryScope>;
+  readonly subjectId: string;
+  readonly tenantId: string;
+}
+interface InvocationToolGrantSet {
+  readonly revision: string;
+  readonly toolIds: ReadonlyArray<string>;
+}
+interface InvocationAuthorityRef {
+  readonly id: string;
+}
+interface InvocationAuthority {
+  readonly agentId: string;
+  readonly allowedActorOpenIds?: ReadonlyArray<string>;
+  readonly conversationId?: string;
+  readonly endpointId?: string;
+  readonly instanceId: string;
+  readonly memory?: InvocationMemoryAuthority;
+  readonly runId: string;
+  readonly sessionKey: string;
+  readonly sourceMessageId: string;
+  readonly tenantKey: string;
+  readonly toolGrantSet: InvocationToolGrantSet;
+}
+declare class InvalidInvocationAuthority extends Error {
+  readonly name = "InvalidInvocationAuthority";
+}
+interface InvocationAuthorityIdentity {
+  next(): string;
+}
+declare function createInvocationAuthority(authority: InvocationAuthority, identity?: InvocationAuthorityIdentity): InvocationAuthorityRef;
+declare function resolveInvocationAuthority(reference: InvocationAuthorityRef): InvocationAuthority;
+//#endregion
+//#region src/core/application/tool-execution/authority/tool-risk-policy.d.ts
+type ToolRisk = "observe" | "mutate" | "irreversible" | "host-control";
+type ToolIdempotency = "none" | "supported" | "required";
+declare function requiresToolApproval(risk: ToolRisk): boolean;
+//#endregion
+//#region src/core/application/tool-execution/brokerage/tool-broker-ports.d.ts
+interface AuthorizationPolicyState {
+  readonly epoch: number;
+  readonly revokedToolIds: ReadonlyArray<string>;
+}
+interface AuthorizationPolicyProvider {
+  current(): Effect.Effect<AuthorizationPolicyState, unknown>;
+}
+interface ToolApprovalRequest {
+  readonly approvalId: string;
+  readonly agentId: string;
+  readonly instanceId: string;
+  readonly inputDigest: string;
+  readonly operationId: string;
+  readonly runId: string;
+  readonly sessionKey: string;
+  readonly tenantKey: string;
+  readonly callId: string;
+  readonly toolId: string;
+  readonly toolVersion: string;
+  readonly risk: ToolRisk;
+}
+interface ToolApprovalService {
+  consume(request: ToolApprovalRequest): Effect.Effect<boolean, unknown>;
+}
+interface ToolExecutionOrigin {
+  readonly allowedActorOpenIds: ReadonlyArray<string>;
+  readonly conversationId?: string;
+  readonly endpointId: string;
+  readonly tenantKey: string;
+}
+interface ToolExecutionContext {
+  readonly agentId: string;
+  readonly callId: string;
+  readonly instanceId: string;
+  readonly memory?: InvocationMemoryAuthority;
+  readonly operationId?: string;
+  readonly origin?: ToolExecutionOrigin;
+  readonly policyEpoch: number;
+  readonly runId: string;
+  readonly sessionKey: string;
+  readonly sourceMessageId?: string;
+  readonly toolId: string;
+  readonly toolVersion: string;
+}
+interface ToolExecutor {
+  execute(input: unknown, context: ToolExecutionContext): Effect.Effect<unknown, unknown>;
+}
+interface ToolDescriptor {
+  readonly createExecutor: (context: {
+    readonly toolId: string;
+    readonly toolVersion: string;
+  }) => ToolExecutor;
+  readonly id: string;
+  readonly idempotency: ToolIdempotency;
+  readonly replayCompleted?: (input: unknown, completedResult: unknown, context: ToolExecutionContext) => Effect.Effect<unknown, unknown>;
+  readonly risk: ToolRisk;
+  readonly version: string;
+}
+interface ToolCatalog {
+  snapshot(): {
+    readonly tools: ReadonlyArray<ToolDescriptor>;
+  };
+}
+interface ToolExecutionRequest {
+  readonly approvalId?: string;
+  readonly authority: InvocationAuthorityRef;
+  readonly callId: string;
+  readonly input: unknown;
+  readonly operationId?: string;
+  readonly toolId: string;
+  readonly version: string;
+}
+declare class ToolExecutorInputRejected extends Error {
+  readonly name = "ToolExecutorInputRejected";
+}
+//#endregion
+//#region src/core/application/tool-execution/contracts/rivus-runtime-tool.d.ts
+declare const RIVUS_RUNTIME_TOOL_IDS: readonly ["read", "bash", "edit", "write", "grep", "find", "ls"];
+type RivusRuntimeToolId = (typeof RIVUS_RUNTIME_TOOL_IDS)[number];
+interface RivusRuntimeToolGrantSet {
+  readonly revision: string;
+  readonly toolIds: ReadonlyArray<RivusRuntimeToolId>;
+}
+declare function isRivusRuntimeToolId(value: string): value is RivusRuntimeToolId;
+//#endregion
+export { RegisteredRivusSkill as $, AgentModelContentObserver as A, RivusToolExecutionOrigin as B, InvocationMemoryAuthority as C, resolveInvocationAuthority as D, createInvocationAuthority as E, RivusMemoryAuthority as F, RivusToolIdempotency as G, RivusToolFactoryContext as H, RivusMemoryScope as I, ModelChangeBoundaryDeadlineError as J, RivusToolInputRejected as K, RivusResolvedToolDescriptor as L, AgentModelOutputObservation as M, RegisteredRivusTool as N, NormalizedAgentInvocation as O, RivusHostToolDescriptor as P, RunAdmissionOptions as Q, RivusToolDescriptor as R, InvocationAuthorityRef as S, InvocationToolGrantSet as T, RivusToolGrantSet as U, RivusToolExecutor as V, RivusToolGrantSetOperations as W, RunAdmission as X, ModelChangeClock as Y, RunAdmissionLease as Z, ToolRisk as _, AuthorizationPolicyProvider as a, ModelChangeExecutionBudget as at, InvocationAuthority as b, ToolApprovalService as c, ModelChangeRuntimeContext as ct, ToolExecutionContext as d, ModelReference as dt, RivusSkillDescriptor as et, ToolExecutionOrigin as f, ToolIdempotency as g, ToolExecutorInputRejected as h, isRivusRuntimeToolId as i, ModelChangeBudgetReservation as it, AgentModelInputObservation as j, normalizeAgentInvocation as k, ToolCatalog as l, ModelChangeRuntimePort as lt, ToolExecutor as m, RivusRuntimeToolGrantSet as n, ModelBinding as nt, AuthorizationPolicyState as o, ModelChangePaidCallKind as ot, ToolExecutionRequest as p, RivusToolRisk as q, RivusRuntimeToolId as r, ModelChangeActivationResult as rt, ToolApprovalRequest as s, ModelChangeRestoreResult as st, RIVUS_RUNTIME_TOOL_IDS as t, RivusSkillGrantSet as tt, ToolDescriptor as u, ModelChangeValidationResult as ut, requiresToolApproval as v, InvocationMemoryScope as w, InvocationAuthorityIdentity as x, InvalidInvocationAuthority as y, RivusToolExecutionContext as z };

package/dist/chunks/tool-input-digest.js

@@ -0,0 +1,119 @@
+//#region src/core/application/tool-execution/contracts/rivus-tool.ts
+var RivusToolInputRejected = class extends Error {
+	name = "RivusToolInputRejected";
+};
+//#endregion
+//#region src/core/application/agent-execution/invocation/agent-invocation-identity.ts
+/**
+* Background-session conversationId is captured only from the explicit origin
+* field; when absent it must not fall back to memory, which would expand the
+* association scope beyond the reviewed binding.
+*/
+function normalizeAgentInvocation(origin) {
+	const conversationId = origin.kind === "background-session" ? origin.conversationId : origin.memory?.conversationId;
+	return {
+		allowedActorOpenIds: origin.allowedActorOpenIds,
+		...conversationId ? { conversationId } : {},
+		endpointId: origin.endpointId,
+		...origin.memory ? { memory: origin.memory } : {},
+		sourceMessageId: origin.sourceMessageId,
+		tenantKey: origin.tenantKey
+	};
+}
+//#endregion
+//#region src/core/application/tool-execution/authority/invocation-authority-registry.ts
+const authorities = /* @__PURE__ */ new WeakMap();
+let localAuthoritySequence = 0;
+var InvalidInvocationAuthority = class extends Error {
+	name = "InvalidInvocationAuthority";
+};
+function createInvocationAuthority(authority, identity = { next: () => String(++localAuthoritySequence) }) {
+	const reference = Object.freeze({ id: `authority:${identity.next()}` });
+	authorities.set(reference, normalizeInvocationAuthority(authority));
+	return reference;
+}
+function resolveInvocationAuthority(reference) {
+	const authority = authorities.get(reference);
+	if (!authority) throw new InvalidInvocationAuthority("invocation authority was not issued by this host");
+	return authority;
+}
+function normalizeInvocationAuthority(authority) {
+	if (!isRecord(authority) || typeof authority.sourceMessageId !== "string" || !authority.sourceMessageId.trim()) throw new InvalidInvocationAuthority("invocation authority requires a trusted source message id");
+	if (authority.endpointId !== void 0 && (!authority.endpointId || !authority.endpointId.trim())) throw new InvalidInvocationAuthority("invocation authority requires a trusted endpoint id");
+	return Object.freeze({
+		...authority,
+		...authority.allowedActorOpenIds === void 0 ? {} : { allowedActorOpenIds: Object.freeze([...authority.allowedActorOpenIds]) },
+		...authority.memory === void 0 ? {} : { memory: freezeMemoryAuthority(authority.memory) },
+		toolGrantSet: freezeGrantSet(authority.toolGrantSet)
+	});
+}
+function freezeMemoryAuthority(value) {
+	const scopes = value.audience === "group" ? value.scopes.filter(isGroupMemoryScope) : [...value.scopes];
+	return Object.freeze({
+		...value,
+		scopes: Object.freeze(scopes)
+	});
+}
+function freezeGrantSet(value) {
+	return Object.freeze({
+		revision: value.revision,
+		toolIds: Object.freeze([...value.toolIds])
+	});
+}
+function isGroupMemoryScope(value) {
+	return value === "conversation" || value === "project";
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
+//#region src/core/application/tool-execution/authority/tool-risk-policy.ts
+function requiresToolApproval(risk) {
+	return risk === "irreversible" || risk === "host-control";
+}
+//#endregion
+//#region src/core/application/tool-execution/brokerage/tool-input-digest.ts
+var InvalidStableJson = class extends Error {
+	name = "InvalidStableJson";
+};
+var InvalidToolInput = class extends InvalidStableJson {
+	name = "InvalidToolInput";
+};
+function createToolInputDigest(input, digest) {
+	try {
+		return digest(serializeStableJson(input, /* @__PURE__ */ new Set()));
+	} catch (error) {
+		if (error instanceof InvalidStableJson) throw new InvalidToolInput(error.message);
+		throw error;
+	}
+}
+function normalizeStableJson(value) {
+	return JSON.parse(serializeStableJson(value, /* @__PURE__ */ new Set()));
+}
+function serializeStableJson(value, ancestors) {
+	if (value === null) return "null";
+	if (typeof value === "string" || typeof value === "boolean") return JSON.stringify(value);
+	if (typeof value === "number") {
+		if (!Number.isFinite(value)) throw new InvalidStableJson("stable JSON numbers must be finite");
+		return JSON.stringify(value);
+	}
+	if (typeof value !== "object" || value === null) throw new InvalidStableJson("value must contain only stable JSON values");
+	if (ancestors.has(value)) throw new InvalidStableJson("stable JSON must not contain cycles");
+	ancestors.add(value);
+	try {
+		if (Array.isArray(value)) {
+			const output = [];
+			for (let index = 0; index < value.length; index += 1) {
+				if (!Object.hasOwn(value, index)) throw new InvalidStableJson("stable JSON arrays must not contain holes");
+				output.push(serializeStableJson(value[index], ancestors));
+			}
+			return `[${output.join(",")}]`;
+		}
+		if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) throw new InvalidStableJson("stable JSON objects must be plain objects");
+		return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${serializeStableJson(value[key], ancestors)}`).join(",")}}`;
+	} finally {
+		ancestors.delete(value);
+	}
+}
+//#endregion
+export { requiresToolApproval as a, resolveInvocationAuthority as c, normalizeStableJson as i, normalizeAgentInvocation as l, InvalidToolInput as n, InvalidInvocationAuthority as o, createToolInputDigest as r, createInvocationAuthority as s, InvalidStableJson as t, RivusToolInputRejected as u };