@stigmer/server 3.37.0 → 3.38.0

package/src/domain/agentexecution/platform-rows.ts

@@ -0,0 +1,133 @@
+/**
+ * Platform rows: the MESSAGE_SYSTEM lines the server itself writes into
+ * an execution's transcript, and the transcript rules that keep them.
+ * The runner owns the transcript; these are the few rows only the
+ * platform can write, because only the platform knows the fact they
+ * state (stigmer#980).
+ *
+ * - Stop rows say why a run stopped when the stop came from outside the
+ *   turn. The runner cannot tell a Pause from a Cancel: both reach its
+ *   activity as the same Temporal cancellation (reason CANCELLED), and
+ *   both RPCs signal the engine before they persist the phase
+ *   (lifecycle.ts), so no stored fact distinguishes them in time. The
+ *   invoke workflow knows which stop it is running, so it writes the row
+ *   (workflows/invoke-agent-execution.ts) and the runner writes none.
+ * - A platform marker write is a status update whose messages are all
+ *   MESSAGE_SYSTEM and do not extend the stored transcript: the
+ *   workflow's stop rows and its broken-flow failure lines. A marker is
+ *   appended, never substituted for the transcript. Every runner write
+ *   is a superset of the stored transcript (a resumed runner seeds from
+ *   it, runner/src/harness/turn-context.ts) and the runner only ever
+ *   appends system rows, so a runner write never reads as a marker.
+ *
+ * Messages carry no id (agentexecution/v1/message.proto), so rows are
+ * identified by type and content: the stop copy is these exact
+ * constants, defined once here for the workflow and the merge, and never
+ * matched against copy some other component authors.
+ *
+ * Pure (protos only): the workflow bundle imports this module by direct
+ * path (src/temporal/README.md, workflow-bundle import discipline).
+ */
+import {
+  ExecutionPhase,
+  MessageType,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+
+/** The stop row of a paused execution. Byte-identical to the copy the runner wrote before stigmer#980 moved it here. */
+export const PAUSE_STOP_ROW =
+  "Execution paused by user. Use resume to continue.";
+
+/** The stop row of a cancelled execution: a quiet terminal state, never a failure (stigmer#282). */
+export const CANCEL_STOP_ROW = "Execution was cancelled.";
+
+/** The stop row a phase carries, or undefined for a phase the platform does not explain. */
+export function stopRowForPhase(phase: ExecutionPhase): string | undefined {
+  switch (phase) {
+    case ExecutionPhase.EXECUTION_PAUSED:
+      return PAUSE_STOP_ROW;
+    case ExecutionPhase.EXECUTION_CANCELLED:
+      return CANCEL_STOP_ROW;
+    default:
+      return undefined;
+  }
+}
+
+/** Whether two rows are the same row: messages carry no id, so identity is type and content. */
+function sameRow(a: AgentMessage, b: AgentMessage): boolean {
+  return a.type === b.type && a.content === b.content;
+}
+
+/** Whether transcript ends with tail, row for row. */
+export function endsWithRows(
+  transcript: readonly AgentMessage[],
+  tail: readonly AgentMessage[],
+): boolean {
+  if (tail.length > transcript.length) {
+    return false;
+  }
+  const offset = transcript.length - tail.length;
+  return tail.every((row, i) => sameRow(transcript[offset + i], row));
+}
+
+/**
+ * Whether incoming is a platform marker write against existing: every
+ * incoming row is MESSAGE_SYSTEM, and it does not extend a non-empty
+ * stored transcript (existing is not a row-for-row prefix of incoming).
+ * An all-system write that does extend it is the runner's own growth; a
+ * write onto an empty transcript has nothing to preserve.
+ */
+export function isPlatformMarkerWrite(
+  existing: readonly AgentMessage[],
+  incoming: readonly AgentMessage[],
+): boolean {
+  if (existing.length === 0 || incoming.length === 0) {
+    return false;
+  }
+  if (!incoming.every((row) => row.type === MessageType.MESSAGE_SYSTEM)) {
+    return false;
+  }
+  const extendsExisting =
+    incoming.length >= existing.length &&
+    existing.every((row, i) => sameRow(row, incoming[i]));
+  return !extendsExisting;
+}
+
+/**
+ * Appends a marker write's rows to the transcript; a retry of a marker
+ * already at the transcript's end appends nothing, so the workflow's
+ * activity retries stay idempotent.
+ */
+export function appendPlatformMarker(
+  existing: readonly AgentMessage[],
+  marker: readonly AgentMessage[],
+): AgentMessage[] {
+  if (endsWithRows(existing, marker)) {
+    return [...existing];
+  }
+  return [...existing, ...marker];
+}
+
+/**
+ * The stop row the merge holds last: the stored transcript's final row
+ * when it is the stored phase's own stop row. While the execution rests
+ * in that phase, the row is the platform's, not part of what the runner's
+ * later writes replace; once the phase moves on (a resume), it is
+ * ordinary history and nothing is held.
+ */
+export function heldStopRow(
+  phase: ExecutionPhase,
+  transcript: readonly AgentMessage[],
+): AgentMessage | undefined {
+  const copy = stopRowForPhase(phase);
+  const last = transcript[transcript.length - 1];
+  if (
+    copy === undefined ||
+    last === undefined ||
+    last.type !== MessageType.MESSAGE_SYSTEM ||
+    last.content !== copy
+  ) {
+    return undefined;
+  }
+  return last;
+}

package/src/domain/agentexecution/subscribe.ts

@@ -46,10 +46,12 @@ import type { Logger } from "../../boot/logger.js";
 import type { Authorizer } from "../../extensions/authorizer.js";
 import { callerIdentityOf } from "../../pipeline/interceptors/auth.js";
 import {
+  internalError,
   invalidArgumentError,
   notFoundError,
 } from "../../pipeline/errors.js";
 import { authorizeDirect } from "../../pipeline/steps/authorize.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 
 import { isTranscriptTerminalPhase } from "./phases.js";
@@ -97,9 +99,11 @@ export async function* subscribeExecution(
         id,
         AgentExecutionSchema,
       );
-    } catch {
-      // Go converts every load failure here to the same NotFound.
-      throw notFoundError("AgentExecution", id);
+    } catch (error) {
+      if (error instanceof ResourceNotFoundError) {
+        throw notFoundError("AgentExecution", id);
+      }
+      throw internalError(error, "failed to load agent execution");
     }
 
     yield snapshot;

package/src/domain/agentexecution/update-status.ts

@@ -2,8 +2,8 @@
  * UpdateStatus — ports controller/update_status.go: the runner's
  * progressive status-update RPC and the domain's single merge chokepoint.
  *
- * Chain per Go: ValidateUpdateStatusInput → MergeAndPersistExecution →
- * NotifyStatusObservers → BroadcastToStreams. The merge+persist is ONE
+ * Chain: Authorize → ValidateUpdateStatusInput → MergeAndPersistExecution
+ * → NotifyStatusObservers → BroadcastToStreams. The merge+persist is ONE
  * atomic read-modify-write under the store's per-resource write lock
  * (store.updateResource) — the same discipline SubmitApproval uses,
  * load-bearing now that the append-only approval_event_stream is the
@@ -24,10 +24,14 @@
  * wholesale with the runner's latest complete state, while server-owned
  * fields (approval decisions, the approval_event_stream, the file_review
  * ledger) are preserved/authored here because the runner never sends
- * them.
+ * them. The transcript's platform rows are the same kind of server-owned
+ * state (platform-rows.ts, stigmer#980): a platform marker write is
+ * appended and never replaces the transcript, and a PAUSED or CANCELLED
+ * execution's stop row stays last across the runner's later writes,
+ * because the Pause and Cancel RPCs, the invoke workflow and the runner
+ * all write a stopped execution and nothing orders them.
  *
- * Versus Stigmer Cloud, OSS excludes the Authorize, PublishToRedis, and
- * Publish steps (broadcast rides in-memory channels per ADR 011).
+ * Broadcast rides in-memory channels (ADR 011).
  */
 import { create } from "@bufbuild/protobuf";
 
@@ -78,6 +82,12 @@ import {
   isTerminalExecutionPhase,
   isTranscriptTerminalPhase,
 } from "./phases.js";
+import {
+  appendPlatformMarker,
+  endsWithRows,
+  heldStopRow,
+  isPlatformMarkerWrite,
+} from "./platform-rows.js";
 import {
   applyResponseDecorators,
   notifyStatusObservers,
@@ -257,6 +267,54 @@ export function nonTerminalTranscriptRegression(
   return { reject: false, reason: "" };
 }
 
+/**
+ * The transcript the merge persists, or undefined to keep the stored one.
+ * The stored phase's stop row, when it closes the transcript, is held
+ * aside so the runner's settle write (which never carries it) is judged
+ * against the transcript beneath it, and re-appended after. A platform
+ * marker write is appended; anything else is the runner's write, replaced
+ * wholesale unless the regression guard rejects it.
+ */
+function mergeTranscript(
+  existingPhase: ExecutionPhase,
+  existing: AgentMessage[],
+  incoming: AgentMessage[],
+  executionId: string,
+  logger: Logger,
+): AgentMessage[] | undefined {
+  const held = heldStopRow(existingPhase, existing);
+  const base = held === undefined ? existing : existing.slice(0, -1);
+
+  let next: AgentMessage[];
+  if (isPlatformMarkerWrite(base, incoming)) {
+    next = appendPlatformMarker(base, incoming);
+  } else {
+    const { reject, reason } = nonTerminalTranscriptRegression(
+      existingPhase,
+      base,
+      incoming,
+    );
+    if (reject) {
+      logger.warn(
+        "Rejected status update that would drop committed transcript history for a non-terminal execution; keeping existing messages",
+        {
+          executionId,
+          existingMessages: existing.length,
+          incomingMessages: incoming.length,
+          reason,
+        },
+      );
+      return undefined;
+    }
+    next = incoming;
+  }
+
+  if (held !== undefined && !endsWithRows(next, [held])) {
+    next = [...next, held];
+  }
+  return next;
+}
+
 /**
  * Merges an incoming status update into the execution in place — the
  * runner-owns-the-transcript merge rules, exactly update_status.go
@@ -294,7 +352,8 @@ export function applyUpdateStatusMerge(
   // any update that would drop committed transcript history for a
   // non-terminal execution. The runner owns the transcript and only ever
   // GROWS it in flight; two regressions are rejected at this single
-  // persistence chokepoint:
+  // persistence chokepoint (the platform's own rows are handled first,
+  // see mergeTranscript):
   //  1. A strictly SHORTER transcript — the classic partial write.
   //  2. A transcript that DROPS a committed tool-call id while appending
   //     enough later turns to keep the count equal-or-greater
@@ -305,23 +364,15 @@ export function applyUpdateStatusMerge(
   // post-denial narration redaction), so a content check would reject
   // valid writes.
   if (requestStatus.messages.length > 0) {
-    const { reject, reason } = nonTerminalTranscriptRegression(
+    const merged = mergeTranscript(
       existingPhase,
       existingMessages,
       requestStatus.messages,
+      input.executionId,
+      logger,
     );
-    if (reject) {
-      logger.warn(
-        "Rejected status update that would drop committed transcript history for a non-terminal execution; keeping existing messages",
-        {
-          executionId: input.executionId,
-          existingMessages: existingMessages.length,
-          incomingMessages: requestStatus.messages.length,
-          reason,
-        },
-      );
-    } else {
-      status.messages = requestStatus.messages;
+    if (merged !== undefined) {
+      status.messages = merged;
     }
   }
 

package/src/domain/iampolicy/__tests__/grant-path.test.ts

@@ -14,8 +14,11 @@
  *     fail-open incident class). The absent arm fires the hook with the
  *     spec and no policy, so a composition can still delete a bare tuple
  *     written before the row mirror existed.
- *   - cleanupResource is bidirectional (as target AND as principal),
- *     deduplicated, revoking each row through the same revoke order.
+ *   - cleanupResource is bidirectional (as principal first, then as
+ *     target with the owner rows last), deduplicated, revoking each row
+ *     through the same revoke order; a fault stops it with the owners
+ *     still holding, since an organization's delete runs it before the
+ *     organization's row goes and its owner is the one who retries.
  *   - revokeOrgAccess revokes the account's direct rows on the
  *     organization; the inert org-column arm the cloud carried is gone
  *     (Q-OR-9).
@@ -378,17 +381,19 @@ describe("revoke: onPolicyRevoked before the row delete", () => {
 });
 
 describe("cleanupResource: bidirectional, deduplicated, each row through the revoke order", () => {
-  it("revokes rows where the ref is the resource AND rows where it is the principal", async () => {
+  it("revokes rows where the ref is the principal, then where it is the resource, owners last", async () => {
     const recorded: RecordedEvent[] = [];
     const { policies, path } = pathOver(recorded, recordingLifecycle(recorded));
-    const asResource = orgRole(ALICE, "owner", "acme");
+    const owner = orgRole(ALICE, "owner", "acme");
+    const member = orgRole(BOB, "member", "acme");
     const asPrincipal = triple(
       { kind: "organization", id: "acme" },
       "organization",
       { kind: "agent", id: AGENT },
     );
     const unrelated = orgRole(ALICE, "member", "globex");
-    for (const spec of [asResource, asPrincipal, unrelated]) {
+    // Granted owner first, so the order below is the cleanup's, not the store's.
+    for (const spec of [owner, member, asPrincipal, unrelated]) {
       await path.grant(spec, alice);
     }
     recorded.length = 0;
@@ -399,17 +404,45 @@ describe("cleanupResource: bidirectional, deduplicated, each row through the rev
 
     expect([...policies.rows.keys()]).toEqual([policyIdFor(unrelated)]);
     expect(recorded).toEqual([
-      { kind: "revoked", id: policyIdFor(asResource), relation: "owner" },
-      { kind: "row-delete", id: policyIdFor(asResource) },
       {
         kind: "revoked",
         id: policyIdFor(asPrincipal),
         relation: "organization",
       },
       { kind: "row-delete", id: policyIdFor(asPrincipal) },
+      { kind: "revoked", id: policyIdFor(member), relation: "member" },
+      { kind: "row-delete", id: policyIdFor(member) },
+      { kind: "revoked", id: policyIdFor(owner), relation: "owner" },
+      { kind: "row-delete", id: policyIdFor(owner) },
     ]);
   });
 
+  it("stops at the first fault with the owner rows still in place", async () => {
+    const recorded: RecordedEvent[] = [];
+    const lifecycle = recordingLifecycle(recorded);
+    const { policies, path } = pathOver(recorded, {
+      ...lifecycle,
+      onPolicyRevoked: (event) =>
+        event.spec.relation === "member"
+          ? Promise.reject(new Error("tuple delete refused"))
+          : lifecycle.onPolicyRevoked!(event),
+    });
+    const owner = orgRole(ALICE, "owner", "acme");
+    const member = orgRole(BOB, "member", "acme");
+    for (const spec of [owner, member]) {
+      await path.grant(spec, alice);
+    }
+
+    await expect(
+      path.cleanupResource(
+        create(ApiResourceRefSchema, { kind: "organization", id: "acme" }),
+      ),
+    ).rejects.toThrow("tuple delete refused");
+
+    expect(policies.rows.has(policyIdFor(owner))).toBe(true);
+    expect(policies.rows.has(policyIdFor(member))).toBe(true);
+  });
+
   it("a ref that is both principal and resource of one row revokes it once", async () => {
     const recorded: RecordedEvent[] = [];
     const { path } = pathOver(recorded, recordingLifecycle(recorded));

package/src/domain/iampolicy/grant-path.ts

@@ -59,6 +59,7 @@ import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/
 import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
 import type { IamPolicy } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
 import { IamPolicySchema } from "@stigmer/protos/ai/stigmer/iam/iampolicy/v1/api_pb";
+import { IamRole } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
 import type {
   ApiResourceRef,
   IamPolicySpec,
@@ -78,6 +79,9 @@ import { DuplicatePolicyError } from "./store.js";
 import type { IamPolicyStore } from "./store.js";
 import { refsOf, requireWellFormedTriple } from "./wire-refusals.js";
 
+/** The relation `cleanupResource` revokes last on the ref's own rows. */
+const OWNER_RELATION = IamRole[IamRole.owner];
+
 export interface GrantResult {
   readonly policy: IamPolicy;
   /** True when the triple was already held: no row was written, the hook still fired. */
@@ -99,9 +103,13 @@ export interface IamPolicyGrantPath {
    */
   revokeBySpec(spec: IamPolicySpec): Promise<IamPolicy | undefined>;
   /**
-   * Revoke every row naming the ref as its resource, then every row naming
-   * it as its principal, each through the revoke order; a row that is both
-   * is revoked once. Nothing to clean is a no-op.
+   * Revoke every row naming the ref as its principal, then every row naming
+   * it as its resource with the `owner` rows last, each through the revoke
+   * order; a row that is both is revoked once. Nothing to clean is a no-op.
+   * The order matters where the ref still exists: an organization's delete
+   * runs this before its row goes and fails on the first fault, so a
+   * cleanup that stops partway has not yet removed the owners who may
+   * retry it.
    */
   cleanupResource(ref: ApiResourceRef): Promise<void>;
   /** Revoke every relation the account holds directly on the organization. */
@@ -209,9 +217,15 @@ export function newIamPolicyGrantPath(
     },
 
     async cleanupResource(ref): Promise<void> {
-      const asResource = await policies.findByResource(ref.kind, ref.id);
       const asPrincipal = await policies.findByPrincipal(ref.kind, ref.id);
-      for (const policy of distinctById([...asResource, ...asPrincipal])) {
+      const asResource = await policies.findByResource(ref.kind, ref.id);
+      const isOwner = (policy: IamPolicy): boolean =>
+        policy.spec?.relation === OWNER_RELATION;
+      for (const policy of distinctById([
+        ...asPrincipal,
+        ...asResource.filter((policy) => !isOwner(policy)),
+        ...asResource.filter(isOwner),
+      ])) {
         await revokeRow(policy);
       }
     },