deepline 0.3.44 → 0.3.45

package/dist/bundling-sources/shared_libs/play-runtime/tool-call/index.ts

@@ -0,0 +1,291 @@
+import type {
+  ToolCallDependencies,
+  ToolCallInput,
+  ToolCallJob,
+  ToolCallReceiptLease,
+  ToolCallResultFormat,
+  ToolResultReceipts,
+} from './contract';
+import { ToolCallReceiptLeaseLostError } from './contract';
+
+export {
+  createRuntimeStepToolResultReceipts,
+  type RuntimeStepToolResultReceiptStore,
+  type RuntimeStepToolResultReceiptsInput,
+} from './runtime-step-receipts-adapter';
+export {
+  createToolCallReceiptCohortJob,
+  ToolCallReceiptCohortWaitTimeoutError,
+  type ToolCallReceiptCohort,
+  type ToolCallReceiptCohortJob,
+  type ToolCallReceiptCohortMember,
+  type ToolCallReceiptCohortMemberState,
+  type ToolCallReceiptCohortStore,
+  type ToolCallReceiptRecord,
+} from './receipt-cohort';
+export {
+  createNativeBatchToolCallJob,
+  type NativeBatchOwnedToolCallMember,
+  type NativeBatchToolCallInput,
+  type NativeBatchToolCallJob,
+  type NativeBatchToolCallMember,
+} from './native-batch';
+export {
+  createAlwaysFreshToolCallAdapter,
+  type AlwaysFreshToolCall,
+  type AlwaysFreshToolCallInput,
+} from './always-fresh-adapter';
+
+export type {
+  ToolCallCompatibilityIdentity,
+  ToolCallDependencies,
+  ToolCallDispatcher,
+  ToolCallInput,
+  ToolCallJob,
+  ToolCallReceiptLease,
+  ToolCallReceiptRecoverySource,
+  ToolCallResultFormat,
+  ToolCallPersistence,
+  ToolResultReceipts,
+} from './contract';
+export { ToolCallReceiptLeaseLostError } from './contract';
+
+/**
+ * Adapts a receipt lifecycle that is already owned by a higher-level runtime
+ * job.  This is a composition seam, not a second receipt implementation.
+ *
+ * PlayContext's direct-call path currently owns a richer runtime receipt
+ * protocol: completed-cache publication, non-idempotent execution locks,
+ * auth-scope re-keying, and external-call-slot retention.  Once it has
+ * claimed that protocol's receipt, ToolCall can still own the call boundary
+ * (validation and dispatch) without trying to claim or terminally write the
+ * same receipt a second time.  The outer job remains the sole durable owner.
+ *
+ * Do not use this for a new caller. New runtimes should provide a real
+ * ToolResultReceipts Adapter. This exists only while PlayContext's historical
+ * receipt state machine is being migrated behind the Tool Call Module.
+ */
+export function createExternallyOwnedToolResultReceipts(input: {
+  resultReceiptKey: string;
+  ownerRunId: string;
+  leaseId?: string | null;
+}): ToolResultReceipts {
+  const resultReceiptKey = input.resultReceiptKey.trim();
+  const ownerRunId = input.ownerRunId.trim();
+  if (!resultReceiptKey) {
+    throw new Error('External Tool Result Receipt needs a receipt key.');
+  }
+  if (!ownerRunId) {
+    throw new Error('External Tool Result Receipt needs an owner run id.');
+  }
+  // A completed-cache-only receipt has no ordinary lease. It is still owned
+  // by the outer operation for this invocation, so give ToolCall a local
+  // identity solely for its in-process contract checks.
+  const lease = {
+    leaseId: input.leaseId?.trim() || 'outer-runtime-owner',
+    ownerRunId,
+  };
+  const assertKeyAndLease = (candidate: {
+    resultReceiptKey: string;
+    lease?: ToolCallReceiptLease;
+  }): void => {
+    if (candidate.resultReceiptKey !== resultReceiptKey) {
+      throw new Error('ToolCall used a receipt outside its owned boundary.');
+    }
+    if (
+      candidate.lease &&
+      (candidate.lease.leaseId !== lease.leaseId ||
+        candidate.lease.ownerRunId !== lease.ownerRunId)
+    ) {
+      throw new ToolCallReceiptLeaseLostError(resultReceiptKey);
+    }
+  };
+
+  return {
+    async claim(candidate) {
+      assertKeyAndLease({ resultReceiptKey: candidate.resultReceiptKey });
+      if (candidate.ownerRunId !== ownerRunId) {
+        throw new ToolCallReceiptLeaseLostError(resultReceiptKey);
+      }
+      return { kind: 'owned', lease };
+    },
+    async recover(candidate) {
+      assertKeyAndLease({ resultReceiptKey: candidate.resultReceiptKey });
+      throw new Error(
+        'An externally owned Tool Result Receipt cannot recover through ToolCall.',
+      );
+    },
+    async heartbeat(candidate) {
+      assertKeyAndLease(candidate);
+      // The outer runtime owns durable heartbeating / execution locks. Returning
+      // active here deliberately avoids a duplicate heartbeat write.
+      return 'active';
+    },
+    async complete(candidate) {
+      assertKeyAndLease(candidate);
+      // The outer runtime atomically publishes the result, including its
+      // cache-only convergence behaviour. A second completion here would alter
+      // that race and can overwrite its execution metadata.
+      return { kind: 'stored', result: candidate.result };
+    },
+    async fail(candidate) {
+      assertKeyAndLease(candidate);
+      // Failure publication belongs to the outer state machine because it
+      // classifies auth-scope changes, suspensions, and lost ownership.
+    },
+  };
+}
+
+const RESULT_FORMATS = new Set<ToolCallResultFormat>([
+  'legacy',
+  'v2',
+  'raw-v2',
+]);
+const REVISION_PATTERN = /^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,63})$/;
+
+/**
+ * Creates the runner-portable Tool Call job.
+ *
+ * The job owns the observable receipt lifecycle. The supplied runtime Adapter
+ * retains the current durable result/provider keys during the migration, and
+ * chooses how a direct call or a map batch reaches the provider.
+ */
+export function createToolCallJob(
+  dependencies: ToolCallDependencies,
+): ToolCallJob {
+  return {
+    async call(input: ToolCallInput) {
+      validateToolCall(input);
+      if (isAlwaysFresh(input)) {
+        return await dependencies.dispatcher.dispatch({
+          call: input,
+          providerOperationKey: null,
+          receipt: null,
+        });
+      }
+
+      const compatibility = input.compatibility;
+      if (!compatibility) {
+        throw new Error(
+          'Receipt-backed Tool Call requires compatibility identities.',
+        );
+      }
+      const resultReceipts = dependencies.resultReceipts;
+      if (!resultReceipts) {
+        throw new Error(
+          'Receipt-backed Tool Call requires a Tool Result Receipt Adapter.',
+        );
+      }
+      const receiptKey = compatibility.resultReceiptKey;
+      const claim = await resultReceipts.claim({
+        resultReceiptKey: receiptKey,
+        ownerRunId: input.execution.ownerRunId,
+        force: input.execution.force === true,
+      });
+
+      if (claim.kind === 'completed') return claim.result;
+      if (claim.kind === 'following') {
+        return await resultReceipts.recover({
+          resultReceiptKey: receiptKey,
+          ownerRunId: input.execution.ownerRunId,
+          source: 'in_flight',
+        });
+      }
+
+      const heartbeat = await resultReceipts.heartbeat({
+        resultReceiptKey: receiptKey,
+        lease: claim.lease,
+      });
+      if (heartbeat === 'completed') {
+        return await resultReceipts.recover({
+          resultReceiptKey: receiptKey,
+          ownerRunId: input.execution.ownerRunId,
+          source: 'in_flight',
+        });
+      }
+      if (heartbeat === 'lost') {
+        throw new ToolCallReceiptLeaseLostError(receiptKey);
+      }
+
+      let result;
+      try {
+        result = await dependencies.dispatcher.dispatch({
+          call: input,
+          providerOperationKey: compatibility.providerOperationKey,
+          receipt: claim.lease,
+        });
+      } catch (error) {
+        // Preserve the provider/transport error. A best-effort failure write
+        // records the lifecycle fact but must not hide the caller-visible one.
+        await resultReceipts
+          .fail({
+            resultReceiptKey: receiptKey,
+            lease: claim.lease,
+            error,
+          })
+          .catch(() => undefined);
+        throw error;
+      }
+
+      const completed = await resultReceipts.complete({
+        resultReceiptKey: receiptKey,
+        lease: claim.lease,
+        result,
+      });
+      return completed.result;
+    },
+  };
+}
+
+function validateToolCall(input: ToolCallInput): void {
+  required(input.scope.organizationId, 'organizationId');
+  required(input.scope.playScope, 'playScope');
+  required(input.tool.id, 'tool id');
+  // Historical artifacts can legitimately have no separately discoverable
+  // action-version string. During the compatibility-key migration their
+  // already-derived providerOperationKey remains authoritative; rejecting the
+  // call here would turn a previously valid legacy tool call into a runtime
+  // failure without improving identity safety.
+  required(input.output.intent, 'output intent');
+  required(input.execution.ownerRunId, 'owner run id');
+  if (isAlwaysFresh(input)) {
+    if (input.compatibility !== undefined) {
+      throw new Error(
+        'Always-fresh Tool Call must not carry receipt or provider-operation identities.',
+      );
+    }
+  } else {
+    if (!input.compatibility) {
+      throw new Error(
+        'Receipt-backed Tool Call requires compatibility identities.',
+      );
+    }
+    required(input.compatibility.resultReceiptKey, 'result receipt key');
+    required(
+      input.compatibility.providerOperationKey,
+      'provider operation key',
+    );
+  }
+  if (!RESULT_FORMATS.has(input.output.format)) {
+    throw new Error(
+      `Unsupported Tool Call result format ${String(input.output.format)}.`,
+    );
+  }
+  const revision = input.output.revision;
+  if (
+    revision != null &&
+    (typeof revision !== 'string' || !REVISION_PATTERN.test(revision))
+  ) {
+    throw new Error('Tool Call result revision must be a static identifier.');
+  }
+}
+
+function isAlwaysFresh(input: ToolCallInput): boolean {
+  return input.execution.persistence === 'always-fresh';
+}
+
+function required(value: string, name: string): void {
+  if (!value?.trim()) {
+    throw new Error(`Tool Call requires a non-empty ${name}.`);
+  }
+}

package/dist/bundling-sources/shared_libs/play-runtime/tool-call/native-batch.ts

@@ -0,0 +1,335 @@
+import type { ToolExecuteResult } from '../tool-result';
+import {
+  ToolCallReceiptLeaseLostError,
+  type ToolCallInput,
+  type ToolCallJob,
+  type ToolCallReceiptLease,
+} from './contract';
+import {
+  type ToolCallReceiptCohort,
+  type ToolCallReceiptCohortJob,
+} from './receipt-cohort';
+
+/**
+ * One logical map item which may have a distinct Tool Result Receipt even
+ * though a provider-native batch will execute several items in one request.
+ */
+export type NativeBatchToolCallMember = {
+  memberId: string;
+  call: ToolCallInput;
+  /** Failed-only refresh is a map policy, not part of the scalar ToolCall ABI. */
+  forceFailedRefresh?: boolean;
+  waitMaxAttempts?: number;
+};
+
+export type NativeBatchOwnedToolCallMember = NativeBatchToolCallMember & {
+  receipt: ToolCallReceiptLease;
+  /** Actual member lease expiry supplied by the receipt-cohort Adapter. */
+  leaseExpiresAt?: string | null;
+};
+
+export type NativeBatchToolCallInput = {
+  owner: { runId: string; attempt: number };
+  members: NativeBatchToolCallMember[];
+  /**
+   * Builds the one physical provider call from exactly the receipts this run
+   * owns. Completed and foreign members are intentionally absent: including
+   * them would turn a cache hit into a duplicate provider operation.
+   */
+  buildPhysicalCall(input: {
+    members: NativeBatchOwnedToolCallMember[];
+  }): ToolCallInput;
+  /**
+   * Decodes one aggregate provider result into exactly one result for every
+   * owned receipt. The Module validates the correspondence before publishing
+   * any member terminal fact.
+   */
+  splitResult(input: {
+    result: ToolExecuteResult;
+    members: NativeBatchOwnedToolCallMember[];
+  }):
+    | Array<{ memberId: string; result: ToolExecuteResult }>
+    | Promise<Array<{ memberId: string; result: ToolExecuteResult }>>;
+  /** Keep all owned member leases alive during a long provider batch. */
+  heartbeat?: {
+    /** May derive a real interval from the claimed member leases. */
+    intervalMs:
+      | number
+      | ((input: { members: NativeBatchOwnedToolCallMember[] }) => number);
+    onTransientFailure?(error: unknown): void;
+  };
+};
+
+/** A native batch returns each local member result, including cache followers. */
+export type NativeBatchToolCallJob = {
+  execute(
+    input: NativeBatchToolCallInput,
+  ): Promise<Map<string, ToolExecuteResult>>;
+};
+
+/**
+ * Owns one provider-native map batch.
+ *
+ * The Module composes two deep jobs rather than copying either protocol:
+ * `ToolCallReceiptCohort` owns per-member receipt leases, recovery and terminal
+ * fanout; `ToolCall` owns the physical provider-operation invocation. This
+ * Module supplies the missing semantic rule between them: exactly one
+ * aggregate operation may be dispatched, and it must be split completely
+ * before every owned member receipt is completed.
+ */
+export function createNativeBatchToolCallJob(dependencies: {
+  receiptCohort: ToolCallReceiptCohortJob;
+  /**
+   * The aggregate call is itself a ToolCall job, normally built with the
+   * externally-owned aggregate receipt Adapter. Member receipts remain the
+   * sole durable authority for the native map's terminal results.
+   */
+  physicalToolCall: ToolCallJob;
+}): NativeBatchToolCallJob {
+  return {
+    async execute(input) {
+      validateInput(input);
+      const cohort = await dependencies.receiptCohort.acquire({
+        owner: input.owner,
+        members: input.members.map((member) => ({
+          memberId: member.memberId,
+          resultReceiptKey: memberReceiptKey(member),
+          force: member.call.execution.force === true,
+          forceFailedRefresh: member.forceFailedRefresh,
+          waitMaxAttempts: member.waitMaxAttempts,
+        })),
+        // Do not make locally owned rows wait behind a foreign receipt's
+        // bounded recovery. The first aggregate can run now; any receipt
+        // reclaimed after the wait forms its own later aggregate operation.
+        eager: true,
+      });
+      const executeOwned = async (): Promise<void> => {
+        const owned = ownedMembers(cohort, input.members);
+        if (owned.length === 0) return;
+        const physical = input.buildPhysicalCall({ members: owned });
+        validatePhysicalCall(physical, input.owner);
+        let leaseLost: ToolCallReceiptLeaseLostError | null = null;
+        const heartbeatIntervalMs = input.heartbeat
+          ? typeof input.heartbeat.intervalMs === 'function'
+            ? input.heartbeat.intervalMs({ members: owned })
+            : input.heartbeat.intervalMs
+          : null;
+        const heartbeat =
+          input.heartbeat && heartbeatIntervalMs !== null
+            ? cohort.startHeartbeat({
+                intervalMs: positiveHeartbeatInterval(heartbeatIntervalMs),
+                onLeaseLost(error) {
+                  leaseLost ??= error;
+                },
+                onTransientFailure: input.heartbeat.onTransientFailure,
+              })
+            : null;
+        try {
+          await assertCohortOwned(cohort, heartbeat, leaseLost);
+          const aggregate = await dependencies.physicalToolCall.call(physical);
+          await assertCohortOwned(cohort, heartbeat, leaseLost);
+          let split: Array<{ memberId: string; result: ToolExecuteResult }>;
+          try {
+            split = await input.splitResult({
+              result: aggregate,
+              members: owned,
+            });
+            validateSplit(owned, split);
+          } catch (error) {
+            throw error;
+          }
+          await cohort.complete(split);
+        } catch (error) {
+          // Once the aggregate call begins, a provider/transport failure is a
+          // terminal fact for every owned member. Lease loss is the exception:
+          // a stale owner must not overwrite the new holder's receipt state.
+          if (!(error instanceof ToolCallReceiptLeaseLostError)) {
+            await failOwned(cohort, owned, error);
+          }
+          throw error;
+        } finally {
+          heartbeat?.stop();
+        }
+      };
+
+      // Start the known-owned aggregate before foreign receipt hydration. The
+      // settlement is still awaited before collection, and any newly reclaimed
+      // member gets a distinct physical operation rather than being silently
+      // omitted from this batch.
+      const initialExecution = executeOwned();
+      const settlement = cohort.settle();
+      await initialExecution;
+      await settlement;
+      await executeOwned();
+
+      return await collectMemberResults(cohort, input.members);
+    },
+  };
+}
+
+function ownedMembers(
+  cohort: ToolCallReceiptCohort,
+  members: NativeBatchToolCallMember[],
+): NativeBatchOwnedToolCallMember[] {
+  const owned: NativeBatchOwnedToolCallMember[] = [];
+  for (const member of members) {
+    const state = cohort.member(member.memberId);
+    if (state.kind !== 'owned') continue;
+    owned.push({
+      ...member,
+      receipt: state.lease,
+      ...(state.leaseExpiresAt ? { leaseExpiresAt: state.leaseExpiresAt } : {}),
+    });
+  }
+  return owned;
+}
+
+function positiveHeartbeatInterval(value: number): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    throw new Error(
+      'Native Batch Tool Call heartbeat interval must be positive.',
+    );
+  }
+  return Math.max(1, Math.floor(value));
+}
+
+async function collectMemberResults(
+  cohort: ToolCallReceiptCohort,
+  members: NativeBatchToolCallMember[],
+): Promise<Map<string, ToolExecuteResult>> {
+  const results = new Map<string, ToolExecuteResult>();
+  for (const member of members) {
+    const state = cohort.member(member.memberId);
+    if (state.kind === 'completed') {
+      results.set(member.memberId, state.result);
+      continue;
+    }
+    if (state.kind === 'following' || state.kind === 'recovering') {
+      results.set(member.memberId, await state.result);
+      continue;
+    }
+    if (state.kind === 'failed') throw state.error;
+    throw new Error(
+      `Native Batch Tool Call left owned member ${member.memberId} without a terminal result.`,
+    );
+  }
+  return results;
+}
+
+async function assertCohortOwned(
+  cohort: ToolCallReceiptCohort,
+  heartbeat: { assertOwned(): void } | null,
+  leaseLost: ToolCallReceiptLeaseLostError | null,
+): Promise<void> {
+  heartbeat?.assertOwned();
+  if (leaseLost) throw leaseLost;
+  const status = await cohort.heartbeat();
+  if (status === 'terminal') {
+    throw new ToolCallReceiptLeaseLostError('native-batch-cohort');
+  }
+  heartbeat?.assertOwned();
+  if (leaseLost) throw leaseLost;
+}
+
+async function failOwned(
+  cohort: ToolCallReceiptCohort,
+  owned: NativeBatchOwnedToolCallMember[],
+  error: unknown,
+): Promise<void> {
+  if (owned.length === 0) return;
+  await cohort
+    .fail(owned.map((member) => ({ memberId: member.memberId, error })))
+    // Preserve the provider/split failure. The cohort itself fails closed on a
+    // stale lease, but a best-effort terminal write must not conceal it.
+    .catch(() => undefined);
+}
+
+function validateInput(input: NativeBatchToolCallInput): void {
+  if (!input.owner.runId.trim()) {
+    throw new Error('Native Batch Tool Call requires an owner run id.');
+  }
+  if (!Number.isInteger(input.owner.attempt) || input.owner.attempt < 0) {
+    throw new Error(
+      'Native Batch Tool Call owner attempt must be a non-negative integer.',
+    );
+  }
+  if (input.members.length === 0) {
+    throw new Error('Native Batch Tool Call requires at least one member.');
+  }
+  const memberIds = new Set<string>();
+  for (const member of input.members) {
+    if (!member.memberId.trim()) {
+      throw new Error('Native Batch Tool Call member needs a member id.');
+    }
+    if (memberIds.has(member.memberId)) {
+      throw new Error(
+        `Duplicate Native Batch Tool Call member ${member.memberId}.`,
+      );
+    }
+    memberIds.add(member.memberId);
+    if (member.call.execution.mode !== 'map') {
+      throw new Error('Native Batch Tool Call members must be map calls.');
+    }
+    if (member.call.execution.ownerRunId !== input.owner.runId) {
+      throw new Error(
+        'Native Batch Tool Call member owner does not match the cohort.',
+      );
+    }
+    memberReceiptKey(member);
+  }
+}
+
+function validatePhysicalCall(
+  physical: ToolCallInput,
+  owner: { runId: string },
+): void {
+  if (physical.execution.mode !== 'map') {
+    throw new Error(
+      'Native Batch Tool Call physical operation must be a map call.',
+    );
+  }
+  if (physical.execution.ownerRunId !== owner.runId) {
+    throw new Error(
+      'Native Batch Tool Call physical owner does not match the cohort.',
+    );
+  }
+  if (!physical.compatibility) {
+    throw new Error(
+      'Native Batch Tool Call physical operation requires aggregate compatibility identities.',
+    );
+  }
+}
+
+function memberReceiptKey(member: NativeBatchToolCallMember): string {
+  const receiptKey = member.call.compatibility?.resultReceiptKey?.trim();
+  if (!receiptKey) {
+    throw new Error(
+      'Native Batch Tool Call members require durable result receipt identities.',
+    );
+  }
+  return receiptKey;
+}
+
+function validateSplit(
+  owned: NativeBatchOwnedToolCallMember[],
+  split: Array<{ memberId: string; result: ToolExecuteResult }>,
+): void {
+  const expected = new Set(owned.map((member) => member.memberId));
+  if (split.length !== expected.size) {
+    throw new Error(
+      'Native Batch Tool Call split must yield exactly one result per owned member.',
+    );
+  }
+  for (const entry of split) {
+    if (!expected.delete(entry.memberId)) {
+      throw new Error(
+        `Native Batch Tool Call split returned an unknown or duplicate member ${entry.memberId}.`,
+      );
+    }
+  }
+  if (expected.size > 0) {
+    throw new Error(
+      `Native Batch Tool Call split omitted owned member ${[...expected][0]}.`,
+    );
+  }
+}