@agent-compose/sdk 0.2.3 → 0.2.5

package/src/request-context/request-context.ts

@@ -0,0 +1,302 @@
+/**
+ * RequestContext — one typed bag carrying tenant identity + freeform
+ * per-run state across the boundary between server, dispatch, runner,
+ * workflow body, agent loop, and (future) processors.
+ *
+ * Two halves:
+ *
+ *   - **Reserved keys** are tenant identity + run identity. They are
+ *     authoritative once the server's auth middleware sets them and
+ *     CANNOT be mutated downstream — `set()` on a reserved key throws.
+ *     This is the same multi-tenancy hijack defence we apply at the RLS
+ *     layer: the runner never gets to claim a different `teamId`.
+ *
+ *   - **Freeform user namespace** is plain `set/get/has/delete` for any
+ *     JSON-serialisable values the caller wants to thread through. Used
+ *     by application code (workflows, processors) for their own state.
+ *
+ * Reserved-key authority:
+ *
+ *   ac__teamId        server (auth middleware)
+ *   ac__runId         server (dispatch)
+ *   ac__workflowId    server (dispatch)
+ *   ac__factoryId     server (auth)            -- nullable
+ *   ac__apiKeyScopes  server (auth)
+ *   ac__parentRunId   server (dispatch)        -- nullable
+ *   ac__abortSignal   runner (per-process)     -- not serialised
+ *
+ * Cross-process flow (server → runner):
+ *
+ *   1. Server constructs `RequestContext` at the auth boundary using the
+ *      reserved key authorities listed above.
+ *   2. `serialise()` → JSON shape `{ reserved, user }` (abortSignal stripped).
+ *   3. Dispatch hands the JSON to the runner sandbox via env (or future
+ *      transport).
+ *   4. Runner calls `RequestContext.deserialise(json)` and attaches its
+ *      own `AbortSignal`. Reserved keys are re-frozen on materialisation.
+ *
+ * `invokeChild` propagation: only reserved keys flow to the child; freeform
+ * is per-run by design (cross-run state must be explicit via `input`).
+ */
+
+/** Reserved key namespace prefix — anything starting with this is platform-owned. */
+export const AC_RESERVED_PREFIX = "ac__";
+
+export const AC_TEAM_ID         = "ac__teamId"        as const;
+export const AC_RUN_ID          = "ac__runId"         as const;
+export const AC_WORKFLOW_ID     = "ac__workflowId"    as const;
+export const AC_FACTORY_ID      = "ac__factoryId"     as const;
+export const AC_API_KEY_SCOPES  = "ac__apiKeyScopes"  as const;
+export const AC_PARENT_RUN_ID   = "ac__parentRunId"   as const;
+export const AC_ABORT_SIGNAL    = "ac__abortSignal"   as const;
+
+/** Reserved keys, as a runtime set for guardrails. Includes all keys above. */
+const RESERVED_KEYS: ReadonlySet<string> = new Set([
+  AC_TEAM_ID,
+  AC_RUN_ID,
+  AC_WORKFLOW_ID,
+  AC_FACTORY_ID,
+  AC_API_KEY_SCOPES,
+  AC_PARENT_RUN_ID,
+  AC_ABORT_SIGNAL,
+]);
+
+/** Reserved keys that cross the dispatch boundary as JSON. Excludes `abortSignal`. */
+const SERIALISABLE_RESERVED_KEYS: ReadonlySet<string> = new Set([
+  AC_TEAM_ID,
+  AC_RUN_ID,
+  AC_WORKFLOW_ID,
+  AC_FACTORY_ID,
+  AC_API_KEY_SCOPES,
+  AC_PARENT_RUN_ID,
+]);
+
+/**
+ * Required reserved values to construct a context. `factoryId` and
+ * `parentRunId` are nullable (factory-scoped key absent → null; root run → null).
+ * `abortSignal` is optional and runner-set; not serialised.
+ */
+export interface RequestContextReserved {
+  teamId:        string;
+  runId:         string;
+  workflowId:    string;
+  factoryId:     string | null;
+  apiKeyScopes:  readonly string[];
+  parentRunId:   string | null;
+  abortSignal?:  AbortSignal;
+}
+
+/** Wire shape for crossing the dispatch boundary. `abortSignal` is stripped. */
+export interface RequestContextWire {
+  reserved: {
+    teamId:        string;
+    runId:         string;
+    workflowId:    string;
+    factoryId:     string | null;
+    apiKeyScopes:  readonly string[];
+    parentRunId:   string | null;
+  };
+  user: Record<string, unknown>;
+}
+
+/** Thrown when a caller tries to `set` or `delete` a reserved key downstream. */
+export class ReservedKeyError extends Error {
+  readonly key: string;
+  constructor(key: string) {
+    super(`request-context: "${key}" is reserved and cannot be mutated downstream`);
+    this.name = "ReservedKeyError";
+    this.key = key;
+  }
+}
+
+/** Thrown when freeform `set` receives a non-JSON-serialisable value. */
+export class NonSerialisableValueError extends Error {
+  constructor(key: string, cause: unknown) {
+    super(`request-context: value for "${key}" is not JSON-serialisable`, { cause });
+    this.name = "NonSerialisableValueError";
+  }
+}
+
+function assertJsonSerialisable(key: string, value: unknown, seen = new WeakSet<object>()): void {
+  if (value === null) return;
+
+  const type = typeof value;
+  if (type === "string" || type === "boolean") return;
+  if (type === "number") {
+    if (Number.isFinite(value)) return;
+    throw new NonSerialisableValueError(key, new TypeError("non-finite numbers are not JSON-serialisable"));
+  }
+  if (type !== "object") {
+    throw new NonSerialisableValueError(key, new TypeError(`${type} is not JSON-serialisable`));
+  }
+
+  const objectValue = value as object;
+
+  if (seen.has(objectValue)) {
+    throw new NonSerialisableValueError(key, new TypeError("cyclic values are not JSON-serialisable"));
+  }
+  seen.add(objectValue);
+
+  if (Array.isArray(value)) {
+    for (const item of value) assertJsonSerialisable(key, item, seen);
+    return;
+  }
+
+  if (Object.getPrototypeOf(objectValue) !== Object.prototype) {
+    throw new NonSerialisableValueError(key, new TypeError("only plain objects are JSON-serialisable"));
+  }
+
+  for (const item of Object.values(objectValue)) assertJsonSerialisable(key, item, seen);
+}
+
+/**
+ * Per-run request context. Construct via `RequestContext.fromReserved(...)`
+ * at the auth boundary; downstream code receives an instance and calls
+ * `.get` / `.set` on it.
+ *
+ * Type parameter `U` lets callers narrow the freeform user namespace shape
+ * for `.get`/`.set` typing — defaults to `unknown` (truly freeform).
+ */
+export class RequestContext<U extends Record<string, unknown> = Record<string, unknown>> {
+  private readonly reserved: RequestContextReserved;
+  private readonly user: Map<string, unknown>;
+
+  private constructor(reserved: RequestContextReserved, user: Map<string, unknown>) {
+    this.reserved = Object.freeze({
+      ...reserved,
+      apiKeyScopes: Object.freeze([...reserved.apiKeyScopes]),
+    });
+    this.user = user;
+  }
+
+  // ── Construction ────────────────────────────────────────────────────────────
+
+  /**
+   * Build a context at the auth/dispatch boundary. Callers (server auth
+   * middleware, dispatch) own the reserved values and pass them in once.
+   */
+  static fromReserved(reserved: RequestContextReserved): RequestContext {
+    return new RequestContext(reserved, new Map());
+  }
+
+  /**
+   * Materialise from the wire shape produced by `serialise()`.
+   * Used by the runner after receiving the JSON via env. The runner attaches
+   * its own `AbortSignal` separately via `withAbortSignal()`.
+   */
+  static deserialise(wire: RequestContextWire): RequestContext {
+    const ctx = new RequestContext(
+      { ...wire.reserved, abortSignal: undefined },
+      new Map(Object.entries(wire.user)),
+    );
+    return ctx;
+  }
+
+  /**
+   * Return a new instance with the given abort signal attached. Used by the
+   * runner once it owns a per-process signal.
+   */
+  withAbortSignal(signal: AbortSignal): RequestContext {
+    return new RequestContext(
+      { ...this.reserved, abortSignal: signal },
+      new Map(this.user),
+    );
+  }
+
+  // ── Reserved-key accessors ──────────────────────────────────────────────────
+
+  get teamId():       string             { return this.reserved.teamId; }
+  get runId():        string             { return this.reserved.runId; }
+  get workflowId():   string             { return this.reserved.workflowId; }
+  get factoryId():    string | null      { return this.reserved.factoryId; }
+  get apiKeyScopes(): readonly string[]  { return this.reserved.apiKeyScopes; }
+  get parentRunId():  string | null      { return this.reserved.parentRunId; }
+  get abortSignal():  AbortSignal | undefined { return this.reserved.abortSignal; }
+
+  /** True if the calling key has the given scope. Read-only convenience. */
+  hasScope(scope: string): boolean {
+    return this.reserved.apiKeyScopes.includes(scope);
+  }
+
+  // ── Freeform user namespace ─────────────────────────────────────────────────
+
+  /**
+   * Set a freeform key. Throws `ReservedKeyError` if `key` collides with the
+   * reserved namespace, and `NonSerialisableValueError` if `value` cannot be
+   * JSON-serialised (so cross-process behaviour matches in-process behaviour).
+   */
+  set<K extends keyof U & string>(key: K, value: U[K]): void;
+  set(key: string, value: unknown): void;
+  set(key: string, value: unknown): void {
+    if (RESERVED_KEYS.has(key) || key.startsWith(AC_RESERVED_PREFIX)) {
+      throw new ReservedKeyError(key);
+    }
+    assertJsonSerialisable(key, value);
+    this.user.set(key, value);
+  }
+
+  get<K extends keyof U & string>(key: K): U[K] | undefined;
+  get(key: string): unknown;
+  get(key: string): unknown {
+    return this.user.get(key);
+  }
+
+  has(key: string): boolean {
+    return this.user.has(key);
+  }
+
+  delete(key: string): boolean {
+    if (RESERVED_KEYS.has(key) || key.startsWith(AC_RESERVED_PREFIX)) {
+      throw new ReservedKeyError(key);
+    }
+    return this.user.delete(key);
+  }
+
+  /** Iterate freeform entries only. Reserved keys are not iterable. */
+  entries(): IterableIterator<[string, unknown]> {
+    return this.user.entries();
+  }
+
+  // ── Serialisation ───────────────────────────────────────────────────────────
+
+  /**
+   * Produce the wire shape for crossing the dispatch boundary. `abortSignal`
+   * is stripped; freeform values are passed through (they were validated as
+   * JSON-serialisable on `set`).
+   */
+  serialise(): RequestContextWire {
+    return {
+      reserved: {
+        teamId:       this.reserved.teamId,
+        runId:        this.reserved.runId,
+        workflowId:   this.reserved.workflowId,
+        factoryId:    this.reserved.factoryId,
+        apiKeyScopes: [...this.reserved.apiKeyScopes],
+        parentRunId:  this.reserved.parentRunId,
+      },
+      user: Object.fromEntries(this.user),
+    };
+  }
+
+  /**
+   * Build a child context for an `invokeChild` call: reserved keys propagate
+   * (with `parentRunId` rewritten to the parent's `runId` and `runId`/`workflowId`
+   * supplied by the caller for the child run); freeform DOES NOT propagate.
+   *
+   * Used server-side when dispatch resolves a child invocation; the freeform
+   * namespace is intentionally per-run to keep cross-run state explicit.
+   */
+  forChild(opts: { runId: string; workflowId: string }): RequestContext {
+    return RequestContext.fromReserved({
+      teamId:       this.reserved.teamId,
+      runId:        opts.runId,
+      workflowId:   opts.workflowId,
+      factoryId:    this.reserved.factoryId,
+      apiKeyScopes: this.reserved.apiKeyScopes,
+      parentRunId:  this.reserved.runId,
+    });
+  }
+}
+
+/** Re-export reserved key set for callers that need to filter env or headers. */
+export { SERIALISABLE_RESERVED_KEYS, RESERVED_KEYS };