@openwop/openwop 1.1.3 → 1.1.6

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). */
@@ -96,7 +125,12 @@ export interface RunConfigurable {
 }
 
 export interface CreateRunRequest {
-  workflowId: string;
+  /**
+   * The workflow to run. Required for a normal run; OMITTED for an eval run
+   * (`mode: 'eval'`), which targets `agentId` + `evalSuiteRef` instead
+   * (RFC 0081 §B). The server enforces the conditional requirement.
+   */
+  workflowId?: string;
   inputs?: Record<string, unknown>;
   tenantId?: string;
   scopeId?: string;
@@ -104,6 +138,12 @@ export interface CreateRunRequest {
   configurable?: RunConfigurable;
   tags?: readonly string[];
   metadata?: Record<string, unknown>;
+  /** RFC 0081 §B. `'eval'` makes this run an eval-suite projection (see `evalSuiteRef` + `agentId`). Omit for a normal workflow run. */
+  mode?: 'eval';
+  /** RFC 0081. URI of the `AgentEvalSuite` to run. Required when `mode === 'eval'`. */
+  evalSuiteRef?: string;
+  /** RFC 0081. The manifest agent the eval suite targets. Required when `mode === 'eval'`. */
+  agentId?: string;
 }
 
 export interface CreateRunResponse {
@@ -254,6 +294,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 +701,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 +1038,271 @@ 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;
+}
+
+/* ── Standing agent roster + org-chart (RFC 0086 / 0087) ──────────────── */
+
+/** RFC 0086 §A — a standing agent INSTANCE: a `host:<id>` AgentRef that
+ *  references a manifest/deployment and owns a workflow portfolio. */
+export interface AgentRosterEntry {
+  rosterId: string;
+  persona: string;
+  agentRef: { agentId: string; version?: string; channel?: string };
+  workflows?: string[];
+  owner: { tenantId: string; workspaceId?: string };
+  enabled?: boolean;
+  label?: string;
+  description?: string;
+}
+
+/** Response for `GET /v1/agents/roster` (RFC 0086 §B). */
+export interface AgentRosterResponse {
+  roster: AgentRosterEntry[];
+  total: number;
+}
+
+/** RFC 0087 §A — an org-chart department (a tree node via `parentDepartmentId`). */
+export interface OrgChartDepartment {
+  departmentId: string;
+  name: string;
+  parentDepartmentId: string | null;
+  roles: { roleId: string; name: string }[];
+}
+
+/** RFC 0087 §A — an org-chart member (a roster instance placed in a dept/role). */
+export interface OrgChartMember {
+  rosterId: string;
+  departmentId: string;
+  roleId: string;
+  reportsTo: string | null;
+}
+
+/** RFC 0087 §A — the descriptive org-chart over roster members. Carries no
+ *  authority-bearing field by design (§B `org-position-no-authority-escalation`). */
+export interface AgentOrgChart {
+  owner: { tenantId: string; workspaceId?: string };
+  departments: OrgChartDepartment[];
+  members: OrgChartMember[];
+}
+
+/** Response for `GET /v1/agents/org-chart/{departmentId}` (RFC 0087 §D) — the
+ *  department subtree + the responsibility roll-up (union of member portfolios). */
+export interface OrgChartResponsibilityView {
+  department: OrgChartDepartment;
+  members: OrgChartMember[];
+  responsibilities: string[];
+}
+
+/* ── User-authored agents (sample-extension; non-normative) ─────────────
+ * Backs the workflow-engine sample app's Agents tab. Pack-installed
+ * agents come through `AgentInventoryEntry` above (RFC 0072 §A
+ * normative inventory). The types below mirror the sample-host
+ * `POST /v1/host/sample/agents` create surface — they're scoped to
+ * the sample-extension and may evolve independently of the
+ * normative agent surface. Future RFC promotion would migrate these
+ * to the normative wire shape.
+ */
+
+/** Body for `POST /v1/host/sample/agents`. The server synthesises
+ *  the agentId as `user.<tenantId>.<persona-slug>`. */
+export interface CreateUserAgentRequest {
+  /** Short name; becomes the `@`-mention slug and chat panel label.
+   *  Required, ≤64 chars. */
+  persona: string;
+  /** Longer display name; defaults to the persona when omitted. */
+  label?: string;
+  description?: string;
+  /** One of: `chat`, `reasoning`, `coding`, `extraction`. */
+  modelClass: string;
+  /** Inline system prompt body; ≤16 000 chars. The sample-host stores
+   *  it directly (no pack-file ref). */
+  systemPrompt: string;
+  /** Capability ids the agent is allowed to call; ≤32 entries. */
+  toolAllowlist?: string[];
+  memoryShape?: {
+    scratchpad?: boolean;
+    conversation?: boolean;
+    longTerm?: boolean;
+  };
+  /** 0.0-1.0; decisions below this are surfaced as low-confidence. */
+  confidenceThreshold?: number;
+}
+
+/** Response body for `POST /v1/host/sample/agents` — shaped to
+ *  match `AgentInventoryEntry` minus normative-only fields, so a
+ *  follow-up `GET /v1/agents` returns a row of the same shape. */
+export interface UserAgentRecord {
+  agentId: string;
+  persona: string;
+  label: string;
+  description?: string;
+  modelClass: string;
+  packName: string;
+  packVersion: string;
+  toolAllowlist: string[];
+  memoryShape: {
+    scratchpad: boolean;
+    conversation: boolean;
+    longTerm: boolean;
+  };
+  confidenceThreshold?: number;
+  hasHandoffSchemas: false;
+}
+
+/** One installable agent-pack summary from the sample host's local
+ *  registry mirror (`GET /v1/host/sample/registry/agent-packs`). */
+export interface AgentPackSummary {
+  /** Pack name, e.g. `core.openwop.agents.code-reviewer`. */
+  name: string;
+  version: string;
+  description?: string;
+  /** Personas declared by the pack's `agents[]` (per RFC 0003). */
+  personas: string[];
+  /** True when at least one of the pack's agents is registered in
+   *  this host's in-process AgentRegistry. */
+  installed: boolean;
+}
+
+export interface AgentPackRegistryResponse {
+  packs: AgentPackSummary[];
+  total: number;
+}
+
+export interface InstallAgentPackRequest {
+  /** Must start with `core.openwop.agents.` — the sample's install
+   *  route filters to that namespace. */
+  name: string;
+  /** Defaults to `1.0.0` when omitted. */
+  version?: string;
+}
+
+export interface InstallAgentPackResponse {
+  name: string;
+  version: string;
+  /** True when the pack was newly installed; false when it was
+   *  already present in the registry. */
+  installed: boolean;
+  alreadyInstalled: boolean;
+}
+
+// ── RFC 0081 — Agent evaluation (eval-summary.schema.json) ─────────────
+
+/** Abstract model class (RFC 0002 / RFC 0003 manifest vocabulary). */
+export type AgentModelClass =
+  | 'reasoning'
+  | 'writing'
+  | 'coding'
+  | 'research'
+  | 'classification'
+  | 'general';
+
+/** A redaction-safe safety finding ({kind, severity} descriptor — never excerpted content). */
+export interface EvalSafetyFinding {
+  kind: string;
+  severity: 'low' | 'medium' | 'high' | 'critical';
+}
+
+/** Per-task result on an `EvalSummary` (content-free: scores + scalars + ids). */
+export interface EvalTaskResult {
+  taskId: string;
+  score: number;
+  passed: boolean;
+  costUsd?: number;
+  latencyMs?: number;
+  schemaValid?: boolean;
+  safetyFindings?: readonly EvalSafetyFinding[];
+}
+
+/** The regression block on an `EvalSummary` (RFC 0081 §D `regression` mode). */
+export interface EvalRegression {
+  baselineRunId: string;
+  scoreDelta: number;
+  diffRef?: string;
+}
+
+/**
+ * RFC 0081 §C — the terminal scorecard of an eval run, read via
+ * `client.runs.evalSummary(runId)`. Content-free: scores, scalars, ids, and
+ * redaction-safe safety descriptors only (`eval-summary-no-content-leak`).
+ */
+export interface EvalSummary {
+  suiteId: string;
+  suiteVersion: string;
+  evaluatedModelClass?: AgentModelClass;
+  aggregateScore: number;
+  passed: boolean;
+  taskCount: number;
+  passedCount: number;
+  totalCostUsd?: number;
+  tasks: readonly EvalTaskResult[];
+  regression?: EvalRegression;
+}
+
+// ── RFC 0082 — Agent deployment lifecycle ─────────────────────────────
+
+/** The seven-state deployment lifecycle (RFC 0082 §C). */
+export type DeploymentState =
+  | 'draft'
+  | 'test'
+  | 'staged'
+  | 'active'
+  | 'paused'
+  | 'deprecated'
+  | 'rolled-back';
+
+/**
+ * RFC 0082 §C — a per-(agentId, version) deployment record, returned by
+ * `client.agents.listDeployments` / `transitionDeployment`. Host-runtime state
+ * distinct from the immutable manifest and the registry's published tags.
+ */
+export interface AgentDeployment {
+  agentId: string;
+  version: string;
+  state: DeploymentState;
+  canaryPercent?: number;
+  rollbackPointer?: string;
+  channels?: readonly string[];
+  evalRunId?: string;
+  approvalGateId?: string;
+}
+
+/**
+ * RFC 0082 §E — the `transitionDeployment` request body. The host authorizes it
+ * fail-closed (RFC 0049 `deploy:*`), runs any RFC 0051 approvalGate, and enforces
+ * RFC 0081 `requiredEval` before emitting `deployment.promoted`.
+ */
+export interface AgentDeploymentTransition {
+  version: string;
+  transition: 'promote' | 'pause' | 'deprecate' | 'rollback' | 'adjust-canary';
+  toState?: DeploymentState;
+  channel?: string;
+  canaryPercent?: number;
+  evalRunId?: string;
+  reason?: string;
+}