@rivus/agent 0.5.2 → 0.6.1

package/dist/pi-tool-proxy.d.ts

@@ -0,0 +1,194 @@
+import { s as AgentLoopInput } from "./agent-loop.js";
+import { c as MemoryScope, t as AgentMemoryAuthority } from "./agent-memory.js";
+import { A as RivusToolRisk, D as RivusToolGrantSet, b as RivusResolvedToolDescriptor, g as RivusPluginCatalog, m as RivusHostToolDescriptor } from "./rivus-plugin.js";
+import { ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+//#region src/domain/recovery-action.d.ts
+interface RecoveryAction {
+  readonly actorId: string;
+  readonly at: string;
+  readonly note: string;
+}
+declare class InvalidRecoveryAction extends Error {
+  readonly name = "InvalidRecoveryAction";
+}
+declare function createRecoveryAction(input: RecoveryAction): RecoveryAction;
+//#endregion
+//#region src/application/delegation/tool-operation-ledger.d.ts
+interface ToolOperationBinding {
+  readonly agentId: string;
+  readonly inputDigest: string;
+  readonly instanceId: string;
+  readonly sourceMessageId: string;
+  readonly toolId: string;
+  readonly toolVersion: string;
+}
+type ToolOperationState = {
+  readonly status: "pending";
+} | {
+  readonly result: unknown;
+  readonly status: "completed";
+} | {
+  readonly reason: string;
+  readonly status: "reconciliation-required";
+} | {
+  readonly status: "aborted";
+};
+interface ToolOperationRecord {
+  readonly binding: ToolOperationBinding;
+  readonly operationId: string;
+  readonly reconciliation?: ToolOperationReconciliation;
+  readonly revision: number;
+  readonly state: ToolOperationState;
+}
+interface ToolOperationReconciliation extends RecoveryAction {
+  readonly outcome: "applied" | "not-applied";
+}
+type ToolOperationReconciliationOutcome = {
+  readonly result: unknown;
+  readonly status: "applied";
+} | {
+  readonly status: "not-applied";
+};
+type ToolOperationBeginResult = {
+  readonly status: "acquired";
+} | {
+  readonly result: unknown;
+  readonly status: "completed";
+} | {
+  readonly status: "blocked";
+  readonly reason: string;
+};
+type ToolOperationInspectResult = {
+  readonly status: "missing";
+} | {
+  readonly result: unknown;
+  readonly status: "completed";
+} | {
+  readonly status: "blocked";
+  readonly reason: string;
+};
+interface ToolOperationLedger {
+  abort(operationId: string, binding: ToolOperationBinding): Promise<void>;
+  begin(operationId: string, binding: ToolOperationBinding): Promise<ToolOperationBeginResult>;
+  complete(operationId: string, binding: ToolOperationBinding, result: unknown): Promise<void>;
+  inspect(operationId: string, binding: ToolOperationBinding): Promise<ToolOperationInspectResult>;
+  reconciliationRequired(): ReadonlyArray<ToolOperationRecord>;
+  reconcile(input: {
+    readonly action: RecoveryAction;
+    readonly expectedRevision: number;
+    readonly operationId: string;
+    readonly outcome: ToolOperationReconciliationOutcome;
+  }): Promise<ToolOperationRecord>;
+  requireReconciliation(operationId: string, binding: ToolOperationBinding, reason: string): Promise<void>;
+  unresolvedForSource(sourceMessageId: string): ReadonlyArray<ToolOperationRecord>;
+}
+declare function createToolOperationLedger(options?: {
+  readonly initial?: ReadonlyArray<ToolOperationRecord>;
+  readonly persist?: (record: ToolOperationRecord) => Promise<void>;
+}): ToolOperationLedger;
+//#endregion
+//#region src/application/delegation/tool-authority.d.ts
+interface InvocationAuthorityRef {
+  readonly id: string;
+}
+interface InvocationAuthority {
+  readonly agentId: string;
+  readonly instanceId: string;
+  readonly memory?: AgentMemoryAuthority;
+  readonly runId: string;
+  readonly sessionKey: string;
+  readonly sourceMessageId: string;
+  readonly tenantKey: string;
+  readonly toolGrantSet: RivusToolGrantSet;
+}
+declare class InvalidInvocationAuthority extends Error {
+  readonly name = "InvalidInvocationAuthority";
+}
+declare function createInvocationAuthority(authority: InvocationAuthority): InvocationAuthorityRef;
+//#endregion
+//#region src/application/delegation/tool-broker.d.ts
+interface AuthorizationPolicyState {
+  readonly epoch: number;
+  readonly revokedToolIds: ReadonlyArray<string>;
+}
+interface AuthorizationPolicyProvider {
+  current(): Promise<AuthorizationPolicyState>;
+}
+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: RivusToolRisk;
+}
+interface ToolApprovalService {
+  consume(request: ToolApprovalRequest): Promise<boolean>;
+}
+interface ToolBrokerOptions {
+  readonly approvals: ToolApprovalService;
+  readonly catalog: RivusPluginCatalog;
+  readonly hostTools?: ReadonlyArray<RivusHostToolDescriptor>;
+  readonly policy: AuthorizationPolicyProvider;
+  readonly operations?: ToolOperationLedger;
+}
+interface ToolExecutionRequest {
+  readonly authority: InvocationAuthorityRef;
+  readonly callId: string;
+  readonly toolId: string;
+  readonly version: string;
+  readonly input: unknown;
+  readonly operationId?: string;
+  readonly approvalId?: string;
+}
+interface ToolBroker {
+  execute(request: ToolExecutionRequest): Promise<unknown>;
+}
+declare class ToolInvocationDenied extends Error {
+  readonly name = "ToolInvocationDenied";
+}
+declare function createToolBroker(options: ToolBrokerOptions): ToolBroker;
+//#endregion
+//#region src/infrastructure/pi/pi-tool-proxy.d.ts
+interface PiToolApprovalRequest {
+  readonly agentId: string;
+  readonly allowedActorOpenIds: ReadonlyArray<string>;
+  readonly approvalId: string;
+  readonly callId: string;
+  readonly endpointId: string;
+  readonly inputDigest: string;
+  readonly instanceId: string;
+  readonly operationId: string;
+  readonly risk: RivusToolRisk;
+  readonly runId: string;
+  readonly sessionKey: string;
+  readonly signal?: AbortSignal;
+  readonly sourceMessageId: string;
+  readonly tenantKey: string;
+  readonly toolId: string;
+  readonly toolVersion: string;
+}
+interface PiToolApprovalGateway {
+  requestApproval(request: PiToolApprovalRequest): Promise<void>;
+}
+interface PiToolProxyOptions {
+  readonly agentId: string;
+  readonly approvals: PiToolApprovalGateway;
+  readonly broker: ToolBroker;
+  readonly getActiveInput: () => AgentLoopInput | undefined;
+  readonly instanceId: string;
+  readonly memoryScopes?: ReadonlyArray<MemoryScope>;
+  readonly toolGrantSet: RivusToolGrantSet;
+  readonly tools: ReadonlyArray<RivusResolvedToolDescriptor>;
+}
+declare function createPiToolProxyDefinitions(options: PiToolProxyOptions): ToolDefinition[];
+declare function createPiToolNameResolver(tools: ReadonlyArray<Pick<RivusResolvedToolDescriptor, "id">>): (toolName: string) => string;
+//#endregion
+export { createRecoveryAction as A, ToolOperationReconciliation as C, createToolOperationLedger as D, ToolOperationState as E, InvalidRecoveryAction as O, ToolOperationLedger as S, ToolOperationRecord as T, InvocationAuthorityRef as _, createPiToolProxyDefinitions as a, ToolOperationBinding as b, ToolApprovalRequest as c, ToolBrokerOptions as d, ToolExecutionRequest as f, InvocationAuthority as g, InvalidInvocationAuthority as h, createPiToolNameResolver as i, RecoveryAction as k, ToolApprovalService as l, createToolBroker as m, PiToolApprovalRequest as n, AuthorizationPolicyProvider as o, ToolInvocationDenied as p, PiToolProxyOptions as r, AuthorizationPolicyState as s, PiToolApprovalGateway as t, ToolBroker as u, createInvocationAuthority as v, ToolOperationReconciliationOutcome as w, ToolOperationInspectResult as x, ToolOperationBeginResult as y };

package/dist/pi.d.ts

@@ -1,3 +1,5 @@
+import { a as createPiToolProxyDefinitions, i as createPiToolNameResolver, n as PiToolApprovalRequest, r as PiToolProxyOptions, t as PiToolApprovalGateway } from "./pi-tool-proxy.js";
+import { o as RegisteredRivusSkill } from "./rivus-plugin.js";
 import { ToolDefinition } from "@earendil-works/pi-coding-agent";
 
 //#region src/infrastructure/pi/pi-project-skill-read-tool.d.ts
@@ -9,4 +11,11 @@ declare function createPiProjectSkillReadTool(options: {
   readonly skillPaths: ReadonlyArray<string>;
 }): ToolDefinition;
 //#endregion
-export { ProjectSkillReadDenied, createPiProjectSkillReadTool };
+//#region src/infrastructure/pi/pi-skill-tool.d.ts
+interface PiSkillRuntime {
+  readonly prompt: string;
+  readonly tool?: ToolDefinition;
+}
+declare function createPiSkillRuntime(skills: ReadonlyArray<RegisteredRivusSkill>): PiSkillRuntime;
+//#endregion
+export { type PiSkillRuntime, type PiToolApprovalGateway, type PiToolApprovalRequest, type PiToolProxyOptions, ProjectSkillReadDenied, createPiProjectSkillReadTool, createPiSkillRuntime, createPiToolNameResolver, createPiToolProxyDefinitions };

package/dist/pi.js

@@ -1,5 +1,9 @@
+import { d as requiresToolApproval } from "./agent-memory.js";
+import { l as createPiSkillRuntime, o as createInvocationAuthority, r as createToolInputDigest } from "./tool-input-digest.js";
+import { createHash } from "node:crypto";
 import { isAbsolute, relative } from "node:path";
 import { readFile, realpath, stat } from "node:fs/promises";
+import { Unsafe } from "typebox";
 import { createReadToolDefinition } from "@earendil-works/pi-coding-agent";
 //#region src/infrastructure/pi/pi-project-skill-read-tool.ts
 var ProjectSkillReadDenied = class extends Error {
@@ -30,4 +34,110 @@ async function authorize(path, sources) {
 	throw new ProjectSkillReadDenied("read is restricted to the bound Project Skill sources");
 }
 //#endregion
-export { ProjectSkillReadDenied, createPiProjectSkillReadTool };
+//#region src/infrastructure/pi/pi-tool-proxy.ts
+function createPiToolProxyDefinitions(options) {
+	const names = /* @__PURE__ */ new Set();
+	return options.tools.map((tool) => {
+		const name = toPiToolName(tool.id);
+		if (names.has(name)) throw new Error(`Pi tool name collision: ${name}`);
+		names.add(name);
+		return {
+			description: tool.description,
+			execute: async (callId, input, signal) => {
+				const activeInput = options.getActiveInput();
+				const invocation = activeInput?.invocation;
+				if (!activeInput || !invocation) throw new Error(`tool ${tool.id} requires an active agent run with a trusted invocation`);
+				if (!invocation.tenantKey) throw new Error(`tool ${tool.id} requires a trusted tenant identity`);
+				throwIfAborted(signal ?? activeInput.abortSignal);
+				const inputDigest = createToolInputDigest(input);
+				const operationId = createBoundId("operation", {
+					agentId: options.agentId,
+					inputDigest,
+					instanceId: options.instanceId,
+					sourceMessageId: invocation.sourceMessageId,
+					toolId: tool.id,
+					toolVersion: tool.version
+				});
+				const approvalId = createBoundId("approval", {
+					callId,
+					operationId,
+					runId: activeInput.runId
+				});
+				if (requiresToolApproval(tool.risk)) {
+					if (invocation.allowedActorOpenIds.length === 0) throw new Error(`tool ${tool.id} requires at least one trusted approval actor`);
+					await options.approvals.requestApproval({
+						agentId: options.agentId,
+						allowedActorOpenIds: invocation.allowedActorOpenIds,
+						approvalId,
+						callId,
+						endpointId: invocation.endpointId,
+						inputDigest,
+						instanceId: options.instanceId,
+						operationId,
+						risk: tool.risk,
+						runId: activeInput.runId,
+						sessionKey: activeInput.sessionKey,
+						signal: signal ?? activeInput.abortSignal,
+						sourceMessageId: invocation.sourceMessageId,
+						tenantKey: invocation.tenantKey,
+						toolId: tool.id,
+						toolVersion: tool.version
+					});
+					throwIfAborted(signal ?? activeInput.abortSignal);
+				}
+				const result = await options.broker.execute({
+					authority: createInvocationAuthority({
+						agentId: options.agentId,
+						instanceId: options.instanceId,
+						...invocation.memory ? { memory: {
+							...invocation.memory,
+							scopes: options.memoryScopes ?? []
+						} } : {},
+						runId: activeInput.runId,
+						sessionKey: activeInput.sessionKey,
+						sourceMessageId: invocation.sourceMessageId,
+						tenantKey: invocation.tenantKey,
+						toolGrantSet: options.toolGrantSet
+					}),
+					callId,
+					input,
+					operationId,
+					...requiresToolApproval(tool.risk) ? { approvalId } : {},
+					toolId: tool.id,
+					version: tool.version
+				});
+				return {
+					content: [{
+						text: stringifyToolResult(result),
+						type: "text"
+					}],
+					details: result
+				};
+			},
+			executionMode: "sequential",
+			label: tool.id,
+			name,
+			parameters: Unsafe(tool.inputSchema),
+			promptSnippet: `${name}: ${tool.description}`
+		};
+	});
+}
+function createPiToolNameResolver(tools) {
+	const toolIdsByPiName = new Map(tools.map((tool) => [toPiToolName(tool.id), tool.id]));
+	return (toolName) => toolIdsByPiName.get(toolName) ?? toolName;
+}
+function toPiToolName(toolId) {
+	return `rivus_${toolId.replace(/[^a-zA-Z0-9_-]/g, "_")}`;
+}
+function createBoundId(kind, binding) {
+	return `${kind}:${createHash("sha256").update(JSON.stringify(binding)).digest("hex")}`;
+}
+function throwIfAborted(signal) {
+	if (signal.aborted) throw signal.reason ?? /* @__PURE__ */ new Error("tool execution was aborted");
+}
+function stringifyToolResult(result) {
+	if (typeof result === "string") return result;
+	return JSON.stringify(result ?? null);
+}
+//#endregion
+export { ProjectSkillReadDenied, createPiProjectSkillReadTool, createPiSkillRuntime, createPiToolNameResolver, createPiToolProxyDefinitions };