@openwop/openwop 1.1.3 → 1.1.5

package/src/types.ts

@@ -32,6 +32,10 @@ export interface Capabilities {
     schemaRounds: number;
     envelopesPerTurn: number;
     maxNodeExecutions?: number;
+    /** RFC 0058. Engine-side wall-clock ceiling per run (ms); upper bound for `RunConfigurable.runTimeoutMs`. */
+    maxRunDurationMs?: number;
+    /** RFC 0058. Engine-side agent-loop iteration ceiling; upper bound for `RunConfigurable.maxLoopIterations`. */
+    maxLoopIterations?: number;
   };
   extensions?: Record<string, unknown>;
   // Network-handshake superset (all `(future)` fields per capabilities.md)
@@ -44,6 +48,22 @@ export interface Capabilities {
   minClientVersion?: string;
 }
 
+/**
+ * The `kind` discriminator on a `cap.breached` event payload
+ * (`run-event-payloads.schema.json#capBreached`). The four engine kinds, the
+ * RFC 0008 §K `wasm-*` runtime caps, and the RFC 0058 run-scoped bounds.
+ */
+export type CapBreachedKind =
+  | 'clarification'
+  | 'schema'
+  | 'envelopes'
+  | 'node-executions'
+  | 'wasm-memory'
+  | 'wasm-fuel'
+  | 'wasm-execution-time'
+  | 'run-duration'
+  | 'loop-iterations';
+
 export interface RunSnapshot {
   runId: string;
   workflowId: string;
@@ -83,6 +103,15 @@ export interface RunSnapshot {
 export interface RunConfigurable {
   /** Override the per-run node-execution ceiling. Clamped server-side. */
   recursionLimit?: number;
+  /** RFC 0058. Wall-clock run deadline (ms from `run.started`); clamped to
+   *  `Capabilities.limits.maxRunDurationMs`. Breach → `cap.breached
+   *  { kind: 'run-duration' }` + `run_timeout`. */
+  runTimeoutMs?: number;
+  /** RFC 0058. Agent-loop iteration ceiling (one per orchestrator turn);
+   *  clamped to `Capabilities.limits.maxLoopIterations`. Breach →
+   *  `cap.breached { kind: 'loop-iterations' }` + `loop_limit_exceeded`.
+   *  Ignored unless the host advertises `capabilities.agents.loop.supported`. */
+  maxLoopIterations?: number;
   /** Override AI model for nodes that consume `ctx.config.configurable.model`. */
   model?: string;
   /** Override AI temperature (server SHOULD enforce 0..2). */
@@ -254,6 +283,99 @@ export interface ForkRunResponse {
   eventsUrl: string;
 }
 
+/** RFC 0056 — a non-blocking quality signal on a run/event/node. */
+export type AnnotationSignal =
+  | { kind: 'rating'; rating: number }
+  | { kind: 'flag' }
+  | { kind: 'label'; label: string }
+  | { kind: 'correction'; correction: string };
+
+/** RFC 0056 persisted annotation (`annotation.schema.json`). A side-resource —
+ *  not a replayable run-event-log entry. */
+export interface Annotation {
+  annotationId: string;
+  target: { runId: string; eventId?: string; nodeId?: string };
+  signal: AnnotationSignal;
+  actor: { principalRef: string };
+  note?: string;
+  createdAt: string;
+}
+
+/** RFC 0056 request body for `createAnnotation` (`annotation-create.schema.json`).
+ *  The host assigns `annotationId`/`createdAt`/`actor` and binds `target.runId`. */
+export interface CreateAnnotationRequest {
+  target?: { eventId?: string; nodeId?: string };
+  signal: AnnotationSignal;
+  note?: string;
+}
+
+/** RFC 0059 versioned, tenant·workspace-scoped ground-truth file
+ *  (`workspace-file.schema.json`). The `list` endpoint returns this shape
+ *  minus `content` (metadata only). */
+export interface WorkspaceFile {
+  path: string;
+  content: string;
+  contentType?: string;
+  version: number;
+  etag?: string;
+  updatedAt: string;
+}
+
+/** RFC 0059 request body for `putWorkspaceFile` (`workspace-file-create.schema.json`).
+ *  `path` is URL-bound; the host assigns `version`/`etag`/`updatedAt`.
+ *  Optimistic concurrency is expressed via the `If-Match` header, not the body. */
+export interface PutWorkspaceFileRequest {
+  content: string;
+  contentType?: string;
+}
+
+/**
+ * Response from `GET /v1/runs/{runId}/ancestry` — RFC 0040 §C cross-host
+ * composition parent. `parent: null` for top-level runs (not dispatched
+ * from any other run); otherwise `parent.wellKnownUrl` is set when the
+ * parent is on a different host so callers can walk the chain.
+ *
+ * Capability-gated: hosts not advertising
+ * `capabilities.multiAgent.executionModel.crossHostCausation.ancestryEndpointSupported: true`
+ * return 404; the SDK surfaces that as `null` via `runs.ancestry()`.
+ */
+export interface RunAncestryResponse {
+  runId: string;
+  hostId: string;
+  parent: null | {
+    runId: string;
+    hostId: string;
+    wellKnownUrl?: string;
+    cause: 'mcp-tool-call' | 'a2a-message' | 'core.subWorkflow' | 'core.dispatch';
+  };
+}
+
+/** RFC 0054 — response from `GET /v1/runs/{runId}:diff?against={otherRunId}`.
+ *  Mirror of `run-diff-response.schema.json`. Deterministic, replay-aware
+ *  structured diff of two runs' event sequences + terminal states. */
+export interface RunDiffEventDiff {
+  seq: number;
+  op: 'added' | 'removed' | 'changed';
+  /** Present unless `op === 'added'`. */
+  aEvent?: RunEventDoc;
+  /** Present unless `op === 'removed'`. */
+  bEvent?: RunEventDoc;
+}
+
+export interface RunDiffResponse {
+  /** The `{runId}` run. */
+  a: string;
+  /** The `against` run. */
+  b: string;
+  /** Sequence at which the logs first diverge; null if identical. */
+  divergedAtSeq: number | null;
+  eventDiffs: RunDiffEventDiff[];
+  /** Diff of terminal RunSnapshot states (redaction-safe). */
+  stateDiff: Record<string, unknown>;
+  /** True if either run was in-flight and only a prefix was compared. */
+  truncated?: boolean;
+}
+
 export interface ResolveInterruptRequest {
   resumeValue: unknown;
 }
@@ -568,6 +690,19 @@ export interface AgentDecidedPayload {
   [key: string]: unknown;
 }
 
+/** `memory.written` payload (RFC 0057). Content-free per-write attribution:
+ *  identifiers + non-secret tags only — never the entry content (the read
+ *  side serves that, already SR-1-redacted). `nodeId` is omitted for host
+ *  session-end writes with no node attribution. */
+export interface MemoryWrittenPayload {
+  memoryRef: string;
+  memoryId: string;
+  nodeId?: string;
+  agentId?: string;
+  tags?: string[];
+  [key: string]: unknown;
+}
+
 /** A `RunEventDoc` narrowed to a specific event-type discriminator +
  *  payload shape. Returned by the `isAgent*` type guards in
  *  `event-helpers.ts`. */
@@ -892,3 +1027,30 @@ function extractTraceId(traceparent: string): string | undefined {
   if (!traceId || !/^[0-9a-f]{32}$/i.test(traceId)) return undefined;
   return traceId;
 }
+
+/**
+ * One installed manifest agent, as projected by `GET /v1/agents` /
+ * `GET /v1/agents/{agentId}` (RFC 0072 §A). Read-only — never carries the
+ * system-prompt body, resolved handoff schemas, or credential material (SR-1).
+ */
+export interface AgentInventoryEntry {
+  agentId: string;
+  persona: string;
+  label: string;
+  description?: string;
+  modelClass: string;
+  packName: string;
+  packVersion: string;
+  toolAllowlist: string[];
+  hasHandoffSchemas: boolean;
+  memoryShape?: { scratchpad?: boolean; conversation?: boolean; longTerm?: boolean };
+  confidenceThreshold?: number;
+  /** RFC 0072 §C — optional capability tiers this host does not satisfy, inert here. */
+  degraded?: string[];
+}
+
+/** Response body for `GET /v1/agents` (RFC 0072 §A). */
+export interface AgentInventoryResponse {
+  agents: AgentInventoryEntry[];
+  total: number;
+}