@openwop/openwop 1.1.3 → 1.1.6

package/src/client.ts

@@ -22,6 +22,10 @@ import {
   type ErrorEnvelope,
   type ForkRunRequest,
   type ForkRunResponse,
+  type Annotation,
+  type CreateAnnotationRequest,
+  type WorkspaceFile,
+  type PutWorkspaceFileRequest,
   type GetPromptRequest,
   type InterruptByTokenInspection,
   type DebugBundle,
@@ -41,8 +45,24 @@ import {
   type ResolveInterruptResponse,
   type ResumeRunRequest,
   type ResumeRunResponse,
+  type RunAncestryResponse,
+  type RunDiffResponse,
   type RunEventDoc,
   type RunSnapshot,
+  type AgentInventoryEntry,
+  type AgentInventoryResponse,
+  type AgentRosterEntry,
+  type AgentRosterResponse,
+  type AgentOrgChart,
+  type OrgChartResponsibilityView,
+  type EvalSummary,
+  type AgentDeployment,
+  type AgentDeploymentTransition,
+  type CreateUserAgentRequest,
+  type UserAgentRecord,
+  type AgentPackRegistryResponse,
+  type InstallAgentPackRequest,
+  type InstallAgentPackResponse,
 } from './types.js';
 
 export interface OpenwopClientOptions {
@@ -142,7 +162,7 @@ export class OpenwopClient {
       } catch (err) {
         // Host doesn't advertise the capability → 404. Surface as null so callers
         // can branch on capability discovery without try/catch.
-        if (err instanceof Error && /\b404\b/.test(err.message)) return null;
+        if (err instanceof WopError && err.status === 404) return null;
         throw err;
       }
     },
@@ -215,6 +235,105 @@ export class OpenwopClient {
         headers: this.#mutationHeaders(opts),
       }),
 
+    /**
+     * RFC 0056 — record a non-blocking quality annotation (rating / correction
+     * / label / flag) on a run/event/node. Returns the persisted `Annotation`.
+     * Throws on non-2xx (`501` when the host doesn't advertise
+     * `capabilities.feedback.supported`).
+     */
+    createAnnotation: (
+      runId: string,
+      body: CreateAnnotationRequest,
+      opts: MutationOptions = {},
+    ): Promise<Annotation> =>
+      this.#request<Annotation>({
+        method: 'POST',
+        path: `/v1/runs/${encodeURIComponent(runId)}/annotations`,
+        body,
+        headers: this.#mutationHeaders(opts),
+      }),
+
+    /**
+     * RFC 0056 — list a run's annotations (tenant-scoped). Returns `null` when
+     * the host doesn't advertise `capabilities.feedback` (404/501), so callers
+     * can branch on capability discovery without try/catch.
+     */
+    listAnnotations: async (runId: string): Promise<readonly Annotation[] | null> => {
+      try {
+        const res = await this.#request<{ annotations: Annotation[] }>({
+          method: 'GET',
+          path: `/v1/runs/${encodeURIComponent(runId)}/annotations`,
+        });
+        return res.annotations;
+      } catch (err) {
+        if (err instanceof WopError && (err.status === 404 || err.status === 501)) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0040 §C — fetch the run's immediate parent in the cross-host
+     * composition chain. Returns `parent: null` for top-level runs;
+     * `parent.wellKnownUrl` is set when the parent is on a different
+     * host, so callers walk the chain one hop at a time.
+     *
+     * Returns `null` when the host doesn't advertise
+     * `capabilities.multiAgent.executionModel.crossHostCausation.ancestryEndpointSupported: true`
+     * (the endpoint returns 404 in that case per
+     * `spec/v1/multi-agent-execution.md` §"GET /v1/runs/{runId}/ancestry").
+     */
+    ancestry: async (runId: string): Promise<RunAncestryResponse | null> => {
+      try {
+        return await this.#request<RunAncestryResponse>({
+          method: 'GET',
+          path: `/v1/runs/${encodeURIComponent(runId)}/ancestry`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0054 — deterministic, replay-aware structured diff of two runs
+     * (typically a run and its `:fork`). Requires `runs:read` on BOTH
+     * `runId` and `against`. Returns `null` when the host doesn't
+     * implement the endpoint (404 per `spec/v1/rest-endpoints.md`
+     * §`GET /v1/runs/{runId}:diff`). `divergedAtSeq` is null + `eventDiffs`
+     * empty when the two logs are identical.
+     */
+    diff: async (runId: string, against: string): Promise<RunDiffResponse | null> => {
+      try {
+        return await this.#request<RunDiffResponse>({
+          method: 'GET',
+          path: `/v1/runs/${encodeURIComponent(runId)}:diff?against=${encodeURIComponent(against)}`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0081 §C — the `EvalSummary` scorecard for a terminal eval run (one
+     * started via `runs.create({ mode: 'eval', evalSuiteRef, agentId })`):
+     * aggregate + per-task scores, cost, latency, schema-validity, and
+     * redaction-safe safety findings. Returns `null` when the host doesn't
+     * advertise `capabilities.agents.evalSuite` or the run isn't an eval run
+     * (404). Throws `409` while the run is still in progress.
+     */
+    evalSummary: async (runId: string): Promise<EvalSummary | null> => {
+      try {
+        return await this.#request<EvalSummary>({
+          method: 'GET',
+          path: `/v1/runs/${encodeURIComponent(runId)}/eval-summary`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
     pollEvents: (
       runId: string,
       params: { lastSequence?: number; timeoutSeconds?: number } = {},
@@ -242,6 +361,191 @@ export class OpenwopClient {
       streamEvents({ baseUrl: this.#baseUrl, apiKey: this.#apiKey }, runId, opts),
   };
 
+  // ── Manifest-agent inventory (RFC 0072 §A) ───────────────────────────
+  // Read-only. Gated on `capabilities.agents.manifestRuntime`; both methods
+  // return `null` when the host doesn't advertise it (the endpoints 404).
+  // Dispatch is not here: a manifest agent runs as a `runs.create` whose
+  // workflow node pins it via `WorkflowNode.agent` (RFC 0072 §B).
+  readonly agents = {
+    list: async (): Promise<AgentInventoryResponse | null> => {
+      try {
+        return await this.#request<AgentInventoryResponse>({ method: 'GET', path: '/v1/agents' });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    get: async (agentId: string): Promise<AgentInventoryEntry | null> => {
+      try {
+        return await this.#request<AgentInventoryEntry>({
+          method: 'GET',
+          path: `/v1/agents/${encodeURIComponent(agentId)}`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0082 §C/§E — list a manifest agent's deployment records (per-(agentId,
+     * version) lifecycle state + channels + canary + rollback pointer). Returns
+     * `null` when the host doesn't advertise `capabilities.agents.deployment`
+     * (the endpoint 404s).
+     */
+    listDeployments: async (agentId: string): Promise<readonly AgentDeployment[] | null> => {
+      try {
+        return await this.#request<AgentDeployment[]>({
+          method: 'GET',
+          path: `/v1/agents/${encodeURIComponent(agentId)}/deployments`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0082 §E — request a deployment state transition (promote / pause /
+     * deprecate / rollback / adjust-canary). The host authorizes fail-closed
+     * against the RFC 0049 `deploy:*` scope, runs any RFC 0051 approvalGate, and
+     * enforces RFC 0081 `requiredEval` before emitting `deployment.promoted`.
+     * Returns the updated deployment record. Throws on non-2xx (`403` fail-closed
+     * / `eval_gate_unmet`; `400` `no_active_deployment` / unsupported state).
+     */
+    transitionDeployment: (
+      agentId: string,
+      body: AgentDeploymentTransition,
+      opts: MutationOptions = {},
+    ): Promise<AgentDeployment> =>
+      this.#request<AgentDeployment>({
+        method: 'POST',
+        path: `/v1/agents/${encodeURIComponent(agentId)}/deployments`,
+        body,
+        headers: this.#mutationHeaders(opts),
+      }),
+
+    /**
+     * RFC 0086 §B — list the standing agent roster (named instances + their
+     * workflow portfolios) visible to the caller. Returns `null` when the host
+     * doesn't advertise `capabilities.agents.roster` (the endpoint 404s).
+     */
+    listRoster: async (): Promise<AgentRosterResponse | null> => {
+      try {
+        return await this.#request<AgentRosterResponse>({ method: 'GET', path: '/v1/agents/roster' });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0086 §B — return one standing roster entry. Returns `null` on 404
+     * (no such entry, cross-tenant, or the capability is unadvertised).
+     */
+    getRosterEntry: async (rosterId: string): Promise<AgentRosterEntry | null> => {
+      try {
+        return await this.#request<AgentRosterEntry>({
+          method: 'GET',
+          path: `/v1/agents/roster/${encodeURIComponent(rosterId)}`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0087 §C — return the caller's agent org-chart (departments + roles +
+     * `reportsTo` over roster members; descriptive — confers no authority).
+     * Returns `null` when the host doesn't advertise `capabilities.agents.orgChart`.
+     */
+    getOrgChart: async (): Promise<AgentOrgChart | null> => {
+      try {
+        return await this.#request<AgentOrgChart>({ method: 'GET', path: '/v1/agents/org-chart' });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0087 §D — one department's subtree + responsibility roll-up (the
+     * union of its members' RFC 0086 portfolios). `recursive: false` scopes the
+     * roll-up to direct members. Returns `null` on 404 (unknown/cross-tenant
+     * department, or the capability is unadvertised).
+     */
+    getOrgChartDepartment: async (
+      departmentId: string,
+      opts: { recursive?: boolean } = {},
+    ): Promise<OrgChartResponsibilityView | null> => {
+      const qs = opts.recursive === false ? '?recursive=false' : '';
+      try {
+        return await this.#request<OrgChartResponsibilityView>({
+          method: 'GET',
+          path: `/v1/agents/org-chart/${encodeURIComponent(departmentId)}${qs}`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+  };
+
+  // ── User-authored agents (sample-extension; non-normative) ───────────
+  // Backs the workflow-engine sample app's Agents tab. Pack-installed
+  // agents come through the `.agents` inventory above (RFC 0072 §A).
+  // These methods wrap the `POST/DELETE /v1/host/sample/agents` +
+  // `GET/POST /v1/host/sample/registry/agent-packs` host extensions.
+  // Returns `null` on 404 (capability absent — matches the `.agents`
+  // surface pattern); throws on other failures.
+  readonly userAgents = {
+    create: async (body: CreateUserAgentRequest, opts: MutationOptions = {}): Promise<UserAgentRecord> => {
+      return await this.#request<UserAgentRecord>({
+        method: 'POST',
+        path: '/v1/host/sample/agents',
+        body,
+        ...(opts.idempotencyKey ? { idempotencyKey: opts.idempotencyKey } : {}),
+      });
+    },
+
+    delete: async (agentId: string): Promise<boolean> => {
+      try {
+        await this.#request<void>({
+          method: 'DELETE',
+          path: `/v1/host/sample/agents/${encodeURIComponent(agentId)}`,
+        });
+        return true;
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return false;
+        throw err;
+      }
+    },
+
+    listAvailablePacks: async (): Promise<AgentPackRegistryResponse | null> => {
+      try {
+        return await this.#request<AgentPackRegistryResponse>({
+          method: 'GET',
+          path: '/v1/host/sample/registry/agent-packs',
+        });
+      } catch (err) {
+        if (err instanceof WopError && err.status === 404) return null;
+        throw err;
+      }
+    },
+
+    installPack: async (
+      body: InstallAgentPackRequest,
+    ): Promise<InstallAgentPackResponse> => {
+      return await this.#request<InstallAgentPackResponse>({
+        method: 'POST',
+        path: '/v1/host/sample/registry/agent-packs/install',
+        body,
+      });
+    },
+  };
+
   // ── HITL interrupts (run-scoped + signed-token) ──────────────────────
   readonly interrupts = {
     resolveByRun: (
@@ -471,6 +775,94 @@ export class OpenwopClient {
     },
   };
 
+  // ── Agent workspace files (RFC 0059; gated on capabilities.workspace) ──
+  readonly workspace = {
+    /**
+     * RFC 0059 — list workspace file metadata (no bodies) for the caller's
+     * `{tenant, workspace}`. Optional `prefix` filters the flat `path`
+     * namespace. Returns `null` when the host doesn't advertise
+     * `capabilities.workspace.supported` (501), so callers can branch on
+     * capability discovery without try/catch.
+     */
+    listFiles: async (opts: { prefix?: string } = {}): Promise<readonly WorkspaceFile[] | null> => {
+      const search = new URLSearchParams();
+      if (opts.prefix !== undefined) search.set('prefix', opts.prefix);
+      const qs = search.toString();
+      try {
+        const res = await this.#request<{ files: WorkspaceFile[] }>({
+          method: 'GET',
+          path: `/v1/host/workspace/files${qs ? `?${qs}` : ''}`,
+        });
+        return res.files;
+      } catch (err) {
+        if (err instanceof WopError && err.status === 501) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0059 — read one workspace file. Pass `version` for a historical
+     * snapshot when `capabilities.workspace.versioned`. Returns `null` when
+     * the file is absent (404) or the host doesn't advertise the capability
+     * (501).
+     */
+    getFile: async (path: string, opts: { version?: number } = {}): Promise<WorkspaceFile | null> => {
+      const search = new URLSearchParams();
+      if (opts.version !== undefined) search.set('version', String(opts.version));
+      const qs = search.toString();
+      try {
+        return await this.#request<WorkspaceFile>({
+          method: 'GET',
+          path: `/v1/host/workspace/files/${encodeURIComponent(path)}${qs ? `?${qs}` : ''}`,
+        });
+      } catch (err) {
+        if (err instanceof WopError && (err.status === 404 || err.status === 501)) return null;
+        throw err;
+      }
+    },
+
+    /**
+     * RFC 0059 — atomic create/replace of a workspace file. Pass `ifMatch`
+     * (the file's current `etag`) for optimistic concurrency; a stale token
+     * throws a `WopError` with status `409` (`workspace_conflict`). Content
+     * beyond `capabilities.workspace.maxFileBytes` throws `413`
+     * (`workspace_too_large`). Returns the persisted `WorkspaceFile`.
+     */
+    putFile: (
+      path: string,
+      body: PutWorkspaceFileRequest,
+      opts: MutationOptions & { ifMatch?: string } = {},
+    ): Promise<WorkspaceFile> => {
+      const headers = this.#mutationHeaders(opts);
+      if (opts.ifMatch !== undefined) headers['If-Match'] = opts.ifMatch;
+      return this.#request<WorkspaceFile>({
+        method: 'PUT',
+        path: `/v1/host/workspace/files/${encodeURIComponent(path)}`,
+        body,
+        headers,
+      });
+    },
+
+    /**
+     * RFC 0059 — delete a workspace file. Returns `true` on success (`204`),
+     * `false` when the file is absent (404) or the host doesn't advertise the
+     * capability (501).
+     */
+    deleteFile: async (path: string, opts: MutationOptions = {}): Promise<boolean> => {
+      try {
+        await this.#request<void>({
+          method: 'DELETE',
+          path: `/v1/host/workspace/files/${encodeURIComponent(path)}`,
+          headers: this.#mutationHeaders(opts),
+        });
+        return true;
+      } catch (err) {
+        if (err instanceof WopError && (err.status === 404 || err.status === 501)) return false;
+        throw err;
+      }
+    },
+  };
+
   // ── Internals ────────────────────────────────────────────────────────
   #mutationHeaders(opts: MutationOptions): Record<string, string> {
     const h: Record<string, string> = {};

package/src/event-helpers.ts

@@ -35,6 +35,7 @@ import type {
   AgentReasoningDeltaPayload,
   AgentToolCalledPayload,
   AgentToolReturnedPayload,
+  MemoryWrittenPayload,
   RunEventDoc,
   TypedRunEvent,
 } from './types.js';
@@ -130,6 +131,18 @@ export function isAgentDecided(
   );
 }
 
+/** `memory.written` (RFC 0057). Narrows when `type` matches AND the payload
+ *  carries the required `memoryRef` + `memoryId` identifier strings. */
+export function isMemoryWritten(
+  ev: RunEventDoc,
+): ev is TypedRunEvent<MemoryWrittenPayload> {
+  return (
+    ev.type === 'memory.written' &&
+    hasStringField(ev.payload, 'memoryRef') &&
+    hasStringField(ev.payload, 'memoryId')
+  );
+}
+
 // ─── High-level subscription helper ─────────────────────────────────────
 
 /** Returned by {@link subscribeToAgentReasoning}. Call to cancel the

package/src/index.ts

@@ -42,17 +42,23 @@ export type {
   ResumeRunRequest,
   ResumeRunResponse,
   RunConfigurable,
+  RunDiffEventDiff,
+  RunDiffResponse,
   RunEventDoc,
   RunSnapshot,
   RunStatus,
   StreamMode,
   TypedRunEvent,
+  // RFC 0059 — agent workspace (spec/v1/agent-workspace.md)
+  WorkspaceFile,
+  PutWorkspaceFileRequest,
   AgentReasonedPayload,
   AgentReasoningDeltaPayload,
   AgentToolCalledPayload,
   AgentToolReturnedPayload,
   AgentHandoffPayload,
   AgentDecidedPayload,
+  MemoryWrittenPayload,
   // RFC 0027 + RFC 0028 — Prompt library (spec/v1/prompts.md)
   GetPromptRequest,
   ListPromptsRequest,
@@ -63,6 +69,33 @@ export type {
   PromptVariable,
   RenderPromptRequest,
   RenderPromptResponse,
+  // RFC 0072 §A — Manifest-agent inventory (GET /v1/agents).
+  // Consumed by the workflow-engine sample app's Agents tab + chat
+  // `@` mention picker (2026-05-28 mention-symbol swap).
+  AgentInventoryEntry,
+  AgentInventoryResponse,
+  // RFC 0081 — Agent evaluation (spec/v1/agent-evaluation.md). EvalSummary
+  // scorecard read via `client.runs.evalSummary(runId)` for a `mode:'eval'` run.
+  AgentModelClass,
+  EvalSafetyFinding,
+  EvalTaskResult,
+  EvalRegression,
+  EvalSummary,
+  // RFC 0082 — Agent deployment lifecycle (spec/v1/agent-deployment.md).
+  // `client.agents.listDeployments` / `transitionDeployment`.
+  DeploymentState,
+  AgentDeployment,
+  AgentDeploymentTransition,
+  // Sample-extension surface — user-authored agents
+  // (`POST /v1/host/sample/agents`) + agent-pack registry browser
+  // (`GET/POST /v1/host/sample/registry/agent-packs`). Non-normative;
+  // wraps host-extension routes the sample app authors against.
+  CreateUserAgentRequest,
+  UserAgentRecord,
+  AgentPackSummary,
+  AgentPackRegistryResponse,
+  InstallAgentPackRequest,
+  InstallAgentPackResponse,
 } from './types.js';
 export { streamEvents } from './sse.js';
 export type { EventsStreamContext, EventsStreamOptions } from './sse.js';
@@ -76,6 +109,7 @@ export {
   isAgentToolReturned,
   isAgentHandoff,
   isAgentDecided,
+  isMemoryWritten,
   subscribeToAgentReasoning,
 } from './event-helpers.js';
 export type {