@springbrand/agent-runtime 0.3.0-alpha.25 → 0.3.0-alpha.27

package/src/tools/runtime/interaction/repository.ts

@@ -1,7 +1,8 @@
 import type { SqlTaggedTemplate } from "agents/chat";
 
 // Tool Interaction 的统一定义见 ./index.ts。
-export type ToolInteractionStatus = "pending" | "responded" | "cancelled";
+export type ToolInteractionStatus = "pending" | "responded" | "cancelled" | "ready" | "declined";
+export type ToolInteractionPurpose = "answer" | "prerequisite";
 
 export interface StoredToolInteraction {
   interactionId: string;
@@ -14,6 +15,11 @@ export interface StoredToolInteraction {
   responseJson: string | null;
   createdAt: number;
   respondedAt: number | null;
+  purpose: ToolInteractionPurpose;
+  scopeKey: string | null;
+  version: number;
+  presentationJson: string | null;
+  verifiedUntil: number | null;
 }
 
 export interface NewToolInteraction {
@@ -25,6 +31,11 @@ export interface NewToolInteraction {
   inputJson: string;
   status: ToolInteractionStatus;
   createdAt: number;
+  purpose?: ToolInteractionPurpose;
+  scopeKey?: string | null;
+  version?: number;
+  presentationJson?: string | null;
+  verifiedUntil?: number | null;
 }
 
 type ToolInteractionRow = {
@@ -38,6 +49,11 @@ type ToolInteractionRow = {
   response_json: string | null;
   created_at: number;
   responded_at: number | null;
+  purpose: string;
+  scope_key: string | null;
+  version: number;
+  presentation_json: string | null;
+  verified_until: number | null;
 };
 
 // 把 SQLite 的 Interaction 行转成 Runtime 对象。
@@ -55,6 +71,11 @@ function mapRow(row: ToolInteractionRow): StoredToolInteraction {
     responseJson: row.response_json,
     createdAt: row.created_at,
     respondedAt: row.responded_at,
+    purpose: row.purpose as ToolInteractionPurpose,
+    scopeKey: row.scope_key,
+    version: row.version,
+    presentationJson: row.presentation_json,
+    verifiedUntil: row.verified_until,
   };
 }
 
@@ -71,7 +92,8 @@ export class ToolInteractionRepository {
     const row = this.sql<ToolInteractionRow>`
       SELECT interaction_id, submission_id, request_id,
              tool_call_id, tool_name, input_json,
-             status, response_json, created_at, responded_at
+             status, response_json, created_at, responded_at,
+             purpose, scope_key, version, presentation_json, verified_until
       FROM pi_tool_interactions
       WHERE interaction_id = ${interactionId}
       LIMIT 1
@@ -87,7 +109,7 @@ export class ToolInteractionRepository {
       INSERT INTO pi_tool_interactions (
         interaction_id, submission_id, request_id,
         tool_call_id, tool_name, input_json,
-        status, created_at
+        status, created_at, purpose, scope_key, version, presentation_json, verified_until
       ) VALUES (
         ${interaction.interactionId},
         ${interaction.submissionId},
@@ -96,7 +118,12 @@ export class ToolInteractionRepository {
         ${interaction.toolName},
         ${interaction.inputJson},
         ${interaction.status},
-        ${interaction.createdAt}
+        ${interaction.createdAt},
+        ${interaction.purpose ?? "answer"},
+        ${interaction.scopeKey ?? null},
+        ${interaction.version ?? 1},
+        ${interaction.presentationJson ?? null},
+        ${interaction.verifiedUntil ?? null}
       )
     `;
   }
@@ -106,7 +133,7 @@ export class ToolInteractionRepository {
   // WHERE status='pending' 实现首次响应胜出，不能去掉这个条件；调用方在事务后重读来确认是否真的生效。
   settle(
     interactionId: string,
-    status: Exclude<ToolInteractionStatus, "pending">,
+    status: "responded" | "cancelled",
     respondedAt: number,
     responseJson?: string,
   ): void {
@@ -143,12 +170,15 @@ export class ToolInteractionRepository {
              interaction.request_id, interaction.tool_call_id,
              interaction.tool_name, interaction.input_json,
              interaction.status, interaction.response_json,
-             interaction.created_at, interaction.responded_at
+             interaction.created_at, interaction.responded_at,
+             interaction.purpose, interaction.scope_key, interaction.version,
+             interaction.presentation_json, interaction.verified_until
       FROM pi_tool_interactions interaction
       JOIN pi_submissions submission
         ON submission.submission_id = interaction.submission_id
       WHERE interaction.tool_call_id = ${toolCallId}
         AND interaction.status = 'pending'
+        AND interaction.purpose = 'answer'
         AND submission.status NOT IN (
           'completed', 'aborted', 'skipped', 'error'
         )
@@ -167,13 +197,72 @@ export class ToolInteractionRepository {
              interaction.request_id, interaction.tool_call_id,
              interaction.tool_name, interaction.input_json,
              interaction.status, interaction.response_json,
-             interaction.created_at, interaction.responded_at
+             interaction.created_at, interaction.responded_at,
+             interaction.purpose, interaction.scope_key, interaction.version,
+             interaction.presentation_json, interaction.verified_until
       FROM pi_tool_interactions interaction
       JOIN pi_submissions submission
         ON submission.submission_id = interaction.submission_id
       WHERE interaction.status = 'pending'
         AND submission.status IN ('pending', 'running')
-      ORDER BY interaction.created_at ASC
+        AND submission.abort_reason IS NULL
+      ORDER BY interaction.created_at ASC, interaction.interaction_id ASC
     `.map(mapRow);
   }
+
+  /** Submission-local scope facts, never a cross-Chat account cache. */
+  findDeclinedScope(submissionId: string, scopeKey: string): StoredToolInteraction | null {
+    const row = this.sql<ToolInteractionRow>`
+      SELECT * FROM pi_tool_interactions
+      WHERE submission_id = ${submissionId} AND scope_key = ${scopeKey}
+        AND purpose = 'prerequisite' AND status = 'declined'
+      ORDER BY created_at ASC LIMIT 1
+    `[0];
+    return row ? mapRow(row) : null;
+  }
+
+  listPendingForScope(submissionId: string, scopeKey: string): StoredToolInteraction[] {
+    return this.sql<ToolInteractionRow>`
+      SELECT * FROM pi_tool_interactions
+      WHERE submission_id = ${submissionId} AND scope_key = ${scopeKey}
+        AND purpose = 'prerequisite' AND status = 'pending'
+      ORDER BY created_at ASC, interaction_id ASC
+    `.map(mapRow);
+  }
+
+  /** CAS against both state and version: a late verifier cannot overwrite decline. */
+  updatePrerequisite(
+    interactionId: string,
+    expected: { status: "pending" | "ready"; version: number },
+    update: {
+      status: "pending" | "ready" | "declined";
+      scopeKey: string;
+      presentationJson: string | null;
+      verifiedUntil?: number | null;
+      renew?: boolean;
+    },
+  ): void {
+    this.sql`
+      UPDATE pi_tool_interactions
+      SET status = ${update.status},
+          scope_key = ${update.scopeKey},
+          presentation_json = ${update.presentationJson},
+          verified_until = ${update.verifiedUntil ?? null},
+          version = ${expected.version + (update.renew ? 1 : 0)},
+          responded_at = ${update.status === "pending" ? null : Date.now()}
+      WHERE interaction_id = ${interactionId}
+        AND purpose = 'prerequisite'
+        AND status = ${expected.status} AND version = ${expected.version}
+    `;
+  }
+
+  /** Terminal cleanup also invalidates verified receipts, not just pending UI. */
+  cancelReadyPrerequisites(submissionId: string): void {
+    this.sql`
+      UPDATE pi_tool_interactions SET status = 'cancelled', verified_until = NULL,
+        responded_at = ${Date.now()}
+      WHERE submission_id = ${submissionId} AND purpose = 'prerequisite'
+        AND status = 'ready'
+    `;
+  }
 }

package/src/tools/runtime/prerequisite-contracts.ts

@@ -0,0 +1,31 @@
+/** Safe, Host-owned presentation; never contains credentials or model input. */
+export interface ToolPrerequisitePresentation {
+  readonly kind: string;
+  readonly title: string;
+  readonly description?: string;
+  readonly data?: unknown;
+}
+
+/** A Tool Call ID alone is not a sufficient prerequisite decision identity. */
+export interface ToolPrerequisiteIdentity {
+  readonly id: string;
+  readonly submissionId: string;
+  readonly toolCallId: string;
+  readonly toolName: string;
+  readonly scopeKey: string;
+  readonly version: number;
+}
+
+/** Each call retains its identity; clients may group equal Submission/scope pairs. */
+export interface ToolPrerequisiteRequest extends ToolPrerequisiteIdentity {
+  readonly createdAt: number;
+  readonly presentation: ToolPrerequisitePresentation;
+}
+
+/** Only the backend may decide readiness. Recheck is not a Tool result. */
+export type ToolPrerequisiteDecision = "recheck" | "declined";
+
+/** The one-argument form of respondToolInteraction; legacy (callId, answer) remains valid. */
+export interface ToolPrerequisiteResponse extends ToolPrerequisiteIdentity {
+  readonly decision: ToolPrerequisiteDecision;
+}

package/src/tools/runtime/prerequisite-gate.ts

@@ -0,0 +1,150 @@
+import type { PiToolCandidate, PiToolPrerequisiteContext } from "./contracts";
+import type { StoredToolInteraction, ToolInteractionRepository } from "./interaction";
+import { normalizePrerequisiteCheck } from "./prerequisites";
+
+type Call = { readonly toolCallId: string; readonly signal: AbortSignal };
+
+/** Pre-intent facts only. Pi remains the sole owner of Tool execution/replay. */
+export class HarnessPrerequisiteGate {
+  private readonly checked = new Map<string, { version: number; expiresAt: number }>();
+
+  constructor(private readonly options: {
+    submission: { readonly submissionId: string; readonly requestId: string };
+    interactions: ToolInteractionRepository;
+    transaction: <T>(run: () => T) => T;
+    isSubmissionActive?: () => boolean;
+    onChanged?: (id: string) => void | Promise<void>;
+    /** Unattended calls fail here before creating any human wait. */
+    onNeedsInput?: (toolName: string) => void | Promise<void>;
+  }) {}
+
+  private context(candidate: PiToolCandidate, call: Call): PiToolPrerequisiteContext {
+    return { ...this.options.submission, ...call, toolName: candidate.tool.name };
+  }
+
+  private assertActive(signal: AbortSignal): void {
+    signal.throwIfAborted();
+    if (this.options.isSubmissionActive?.() === false) throw new Error("Tool Submission is no longer active");
+  }
+
+  private read(candidate: PiToolCandidate, input: unknown, call: Call): StoredToolInteraction | null {
+    const row = this.options.interactions.find(`${this.options.submission.submissionId}:${call.toolCallId}`);
+    if (row && (row.requestId !== this.options.submission.requestId ||
+      row.toolName !== candidate.tool.name || row.inputJson !== JSON.stringify(input) ||
+      row.purpose !== "prerequisite")) {
+      throw new Error(`Conflicting durable Tool prerequisite: ${call.toolCallId}`);
+    }
+    return row;
+  }
+
+  async beforeTool(candidate: PiToolCandidate, input: unknown, call: Call): Promise<"ready" | "pending" | "decided"> {
+    this.assertActive(call.signal);
+    const existing = this.read(candidate, input, call);
+    if (existing?.status === "declined" || existing?.status === "cancelled") return "decided";
+    const spec = candidate.prerequisite;
+    if (!spec) throw new Error("The original Tool prerequisite declaration is no longer available");
+    const context = this.context(candidate, call);
+    const scopeKey = await spec.scope(structuredClone(input), context);
+    this.assertActive(call.signal);
+    if (scopeKey !== null && (typeof scopeKey !== "string" || !scopeKey.trim())) {
+      throw new Error("Invalid trusted Tool prerequisite scope");
+    }
+    if (scopeKey === null && !existing) return "ready";
+    const scope = scopeKey ?? existing!.scopeKey!;
+    // Consult refusal before any live check, even for another Tool in this Submission.
+    const declined = this.options.interactions.findDeclinedScope(context.submissionId, scope);
+    if (declined) {
+      this.options.transaction(() => {
+        this.assertActive(call.signal);
+        if (!existing) this.options.interactions.insert({
+          interactionId: `${context.submissionId}:${call.toolCallId}`,
+          ...this.options.submission, toolCallId: call.toolCallId, toolName: candidate.tool.name,
+          inputJson: JSON.stringify(input), purpose: "prerequisite", scopeKey: scope,
+          presentationJson: declined.presentationJson, status: "declined", createdAt: Date.now(),
+        });
+        else if (existing.status === "pending" || existing.status === "ready") {
+          this.options.interactions.updatePrerequisite(existing.interactionId, { status: existing.status, version: existing.version }, {
+            status: "declined", scopeKey: scope, presentationJson: declined.presentationJson,
+          });
+        }
+      });
+      return "decided";
+    }
+    if (existing?.scopeKey === scope && scopeKey !== null) {
+      if (existing.status === "pending") {
+        await this.options.onNeedsInput?.(candidate.tool.name);
+        return "pending";
+      }
+      if (existing.status === "ready" && (existing.verifiedUntil ?? 0) > Date.now()) return "ready";
+    }
+    const check = normalizePrerequisiteCheck(scopeKey === null ? { status: "ready" } : await spec.check(structuredClone(input), {
+      ...context, scopeKey, reason: existing ? "continuation" : "initial",
+    }));
+    this.assertActive(call.signal);
+    if (check.status === "pending") await this.options.onNeedsInput?.(candidate.tool.name);
+    const row = this.options.transaction(() => {
+      this.assertActive(call.signal);
+      const current = this.read(candidate, input, call);
+      // A scope refusal or stop may have won while the Host checked.
+      const refused = this.options.interactions.findDeclinedScope(context.submissionId, scope);
+      if (current?.status === "declined" || current?.status === "cancelled") return current;
+      if (current && (current.version !== existing?.version || current.status !== existing?.status)) return current;
+      const status = refused ? "declined" : check.status;
+      const presentationJson = refused?.presentationJson ?? check.presentationJson ?? current?.presentationJson ?? null;
+      if (!current) {
+        this.options.interactions.insert({
+          interactionId: `${context.submissionId}:${call.toolCallId}`, ...this.options.submission,
+          toolCallId: call.toolCallId, toolName: candidate.tool.name, inputJson: JSON.stringify(input),
+          purpose: "prerequisite", scopeKey: scope, status, presentationJson,
+          verifiedUntil: refused ? null : check.verifiedUntil, createdAt: Date.now(),
+        });
+      } else if (current.status === "pending" || current.status === "ready") {
+        this.options.interactions.updatePrerequisite(current.interactionId, { status: current.status, version: current.version }, {
+          status, scopeKey: scope, presentationJson, verifiedUntil: refused ? null : check.verifiedUntil,
+          renew: current.scopeKey !== scope || check.status === "pending",
+        });
+      }
+      return this.read(candidate, input, call)!;
+    });
+    if (row.status === "ready") {
+      this.checked.set(call.toolCallId, { version: row.version, expiresAt: check.verifiedUntil ?? Date.now() + 60_000 });
+      if (existing?.status === "pending") await this.options.onChanged?.(row.interactionId);
+      return "ready";
+    }
+    await this.options.onChanged?.(row.interactionId);
+    return row.status === "pending" ? "pending" : "decided";
+  }
+
+  /** Safe replay skips beforeTool. Reverify if necessary, but never park after intent. */
+  async authorize(candidate: PiToolCandidate, input: unknown, call: Call): Promise<void> {
+    this.assertActive(call.signal);
+    const row = this.read(candidate, input, call);
+    if (row?.status === "declined" || row?.status === "cancelled") return;
+    const checked = this.checked.get(call.toolCallId);
+    if (row?.status === "ready" && (
+      (row.verifiedUntil ?? 0) > Date.now() ||
+      (checked?.version === row.version && checked.expiresAt > Date.now())
+    )) return;
+    if (row?.status === "pending") throw new Error("Tool prerequisite is still waiting for input");
+    const context = this.context(candidate, call);
+    const scopeKey = await candidate.prerequisite!.scope(structuredClone(input), context);
+    this.assertActive(call.signal);
+    if (scopeKey === null) return;
+    if (typeof scopeKey !== "string" || !scopeKey.trim()) throw new Error("Invalid trusted Tool prerequisite scope");
+    if (this.options.interactions.findDeclinedScope(context.submissionId, scopeKey)) {
+      throw new Error("The user declined this prerequisite. This operation was not executed.");
+    }
+    const check = normalizePrerequisiteCheck(await candidate.prerequisite!.check(structuredClone(input), {
+      ...context, scopeKey, reason: "continuation",
+    }));
+    this.assertActive(call.signal);
+    const latest = this.read(candidate, input, call);
+    if (latest?.status === "declined" || latest?.status === "cancelled") return;
+    if (row && (!latest || latest.version !== row.version || latest.status !== "ready" ||
+      latest.scopeKey !== scopeKey)) throw new Error("The Tool prerequisite wait changed before execution");
+    if (this.options.interactions.findDeclinedScope(context.submissionId, scopeKey)) {
+      throw new Error("The user declined this prerequisite. This operation was not executed.");
+    }
+    if (check.status !== "ready") throw new Error("Tool prerequisite no longer satisfied. This operation was not executed.");
+  }
+}

package/src/tools/runtime/prerequisites.ts

@@ -0,0 +1,108 @@
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+import type { PiToolPrerequisiteCheck, PiToolPrerequisiteSpec } from "./contracts";
+import type { StoredToolInteraction } from "./interaction";
+import type {
+  ToolPrerequisiteIdentity, ToolPrerequisitePresentation, ToolPrerequisiteRequest,
+  ToolPrerequisiteResponse,
+} from "./prerequisite-contracts";
+
+const MAX_RECEIPT_MS = 60_000;
+const MAX_PRESENTATION_BYTES = 64 * 1024;
+
+export function parsePrerequisiteResponse(value: unknown): ToolPrerequisiteResponse | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const input = value as Record<string, unknown>;
+  const strings = ["id", "submissionId", "toolCallId", "toolName", "scopeKey"];
+  if (!strings.every((key) => typeof input[key] === "string" && (input[key] as string).length > 0) ||
+    !Number.isSafeInteger(input.version) || (input.version as number) < 1 ||
+    (input.decision !== "recheck" && input.decision !== "declined")) return null;
+  // Callers may spread the displayed request; display fields never become authority.
+  return {
+    id: input.id as string, submissionId: input.submissionId as string,
+    toolCallId: input.toolCallId as string, toolName: input.toolName as string,
+    scopeKey: input.scopeKey as string, version: input.version as number,
+    decision: input.decision,
+  };
+}
+
+export function matchesPrerequisite(row: StoredToolInteraction | null, identity: ToolPrerequisiteIdentity): row is StoredToolInteraction {
+  return Boolean(row && row.purpose === "prerequisite" &&
+    row.interactionId === identity.id && row.submissionId === identity.submissionId &&
+    row.toolCallId === identity.toolCallId && row.toolName === identity.toolName &&
+    row.scopeKey === identity.scopeKey && row.version === identity.version);
+}
+
+function safePresentation(value: unknown): ToolPrerequisitePresentation {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("Invalid Tool prerequisite presentation");
+  }
+  const input = value as ToolPrerequisitePresentation;
+  if (typeof input.kind !== "string" || !input.kind.trim() ||
+    typeof input.title !== "string" || !input.title.trim() ||
+    (input.description !== undefined && typeof input.description !== "string")) {
+    throw new Error("Invalid Tool prerequisite presentation");
+  }
+  const json = JSON.stringify({
+    kind: input.kind, title: input.title,
+    ...(input.description !== undefined ? { description: input.description } : {}),
+    ...(input.data !== undefined ? { data: input.data } : {}),
+  });
+  if (new TextEncoder().encode(json).byteLength > MAX_PRESENTATION_BYTES) {
+    throw new Error("Tool prerequisite presentation exceeds 64 KiB");
+  }
+  return JSON.parse(json) as ToolPrerequisitePresentation;
+}
+
+/** A receipt is only a short-lived check result, never an authorization grant. */
+export function normalizePrerequisiteCheck(value: PiToolPrerequisiteCheck): {
+  status: "ready" | "pending";
+  presentationJson: string | null;
+  verifiedUntil: number | null;
+} {
+  const now = Date.now();
+  if (value?.status === "ready") {
+    if (value.validUntil !== undefined && (!Number.isFinite(value.validUntil) || value.validUntil <= now)) {
+      throw new Error("Invalid Tool prerequisite verification expiry");
+    }
+    return {
+      status: "ready", presentationJson: null,
+      verifiedUntil: value.validUntil !== undefined && value.validUntil > now
+        ? Math.min(value.validUntil, now + MAX_RECEIPT_MS) : null,
+    };
+  }
+  if (value?.status === "needs-input") {
+    return { status: "pending", presentationJson: JSON.stringify(safePresentation(value.presentation)), verifiedUntil: null };
+  }
+  throw new Error("Invalid Tool prerequisite check result");
+}
+
+export function prerequisitePresentation(row: StoredToolInteraction): ToolPrerequisitePresentation {
+  return safePresentation(JSON.parse(row.presentationJson ?? "null"));
+}
+
+export function projectPrerequisites(rows: readonly StoredToolInteraction[]): ToolPrerequisiteRequest[] {
+  return rows.filter((row) => row.purpose === "prerequisite" && row.status === "pending")
+    .map((row) => ({
+      id: row.interactionId, submissionId: row.submissionId, toolCallId: row.toolCallId,
+      toolName: row.toolName, scopeKey: row.scopeKey!, version: row.version,
+      createdAt: row.createdAt, presentation: prerequisitePresentation(row),
+    }));
+}
+
+export function declinedPrerequisiteResult(
+  row: StoredToolInteraction,
+  input: unknown,
+  spec?: PiToolPrerequisiteSpec,
+): AgentToolResult<unknown> {
+  const presentation = prerequisitePresentation(row);
+  const custom = spec?.declinedResult?.(input, presentation);
+  return custom ? { ...custom, terminate: false } : {
+    content: [{
+      type: "text",
+      text: `The user declined the prerequisite for ${presentation.title}. This operation was not executed.\n\n` +
+        "Try an alternative that does not require this prerequisite. Do not ask again for the current request. " +
+        "If no suitable alternative is available, explain the limitation without claiming the task was completed.",
+    }],
+    details: { declined: true, executed: false },
+  };
+}