@runmark/sdk 0.1.0 → 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.3
+
+- Add typed repository runtime webhook management, evidence pagination, replay, rotation status,
+  run/HITL fetch helpers, and a Standard Webhooks-compatible signature verifier.
+- Add immutable `dev`/`main` endpoint lanes, strict all/selected-agent scopes, disabled-first test
+  setup, repository-wide delivery search/detail APIs, deleted-endpoint history, and claimed attempt
+  URL/timestamp/secret-revision/next-retry evidence.
+
+## 0.1.2
+
+- Add request-ID submission and lookup, durable cancellation, HITL request
+  correlation, active-organization forwarding, and replay-cursor contracts.
+- Add durable response/error types and preserve typed API error codes.
+- Validate and bound JSON/SSE responses, including fragmented CRLF events,
+  malformed envelopes, oversized bodies/events, and reader cancellation.

package/README.md

@@ -1,81 +1,273 @@
-# @skyforge-ai/sdk
+# @runmark/sdk
+
+Runtime lifecycle webhooks use Standard Webhooks signatures and at-least-once delivery. Use
+`verifyWebhookSignature` against the exact raw request bytes before parsing JSON, reject timestamps
+outside the default five-minute window, and deduplicate on the immutable event `id`. Delivery order
+may differ from the run-local `sequence`; use the repository-bound `cursor` for replay ranges.
+
+Webhook payloads are intentionally minimized. Follow the version-pinned run and human-action URLs
+with an authorized repository token when full evidence is required. Endpoint secrets are shown only
+once when created or rotated, and overlapping revisions remain valid for 24 hours.
+
+Endpoints are created disabled and bind immutably to the exact lowercase `dev` or `main` lane.
+Configure an explicit `agent_scope`, send a targeted test while disabled, then enable the endpoint.
+Use `skyforge.webhooks.listRepositoryDeliveries(...)` for repository-wide server-side search and
+cursor pagination, and `skyforge.webhooks.getDelivery(...)` to retrieve the exact persisted body and
+claimed URL/timestamp/revision evidence for every retained attempt. Endpoint edits and rotations
+affect later claims without rewriting earlier attempt evidence.
+
+Server-side TypeScript SDK for calling Skyforge agent chat APIs from trusted
+backend code.
+
+Use this package from Express apps, Next.js route handlers, serverless
+functions, jobs, and backend proxies. Do not use it in browser code.
+
+```text
+Browser
+  -> your backend
+  -> @runmark/sdk
+  -> Skyforge API
+```
+
+Use `@runmark/agent-chat` when you need the browser or React chat UI.
+
+## When To Use It
+
+- Send messages to a configured Skyforge agent branch from your backend.
+- Build an app proxy for `@runmark/agent-chat`.
+- Resume a known Skyforge chat by `chatId`.
+- Attach optional host-app mapping metadata with `externalId`.
+- Build server-side chat recovery, search, or history using agent-scoped chat
+  lookup.
+- Upload, list, and delete files attached to a chat.
+- Stream durable run events and submit human actions.
+
+## Installation
+
+```bash
+npm install @runmark/sdk
+```
+
+## Requirements
+
+- Node.js `24.17.0` or newer
+- A server-side Skyforge API token
+- Native `fetch`, `FormData`, `ReadableStream`, and `AbortSignal`
+
+## Client Setup
 
-Server-side TypeScript SDK for Skyforge agent chat integrations.
+```ts
+import { SkyforgeClient } from "@runmark/sdk";
+
+const skyforge = new SkyforgeClient({
+  apiKey: process.env.SKYFORGE_API_TOKEN!,
+  baseUrl: process.env.SKYFORGE_API_BASE_URL ?? "https://api.skyforge.ai",
+});
+```
 
-This package is internal for now and is not published to npm. `private: true`
-is intentionally retained until a release process, package metadata, and npm
-publishing policy are approved.
+Common server-side environment variables:
 
-## Runtime
+```bash
+SKYFORGE_API_BASE_URL=https://api.skyforge.ai
+SKYFORGE_API_TOKEN=
+SKYFORGE_AGENT_ID=
+SKYFORGE_AGENT_BRANCH_ID=
+```
 
-- Node.js 24.17.0 or newer.
-- Server-only. The SDK throws in browser-like environments.
-- Zero runtime dependencies.
-- Uses native `fetch`, `FormData`, `ReadableStream`, and `AbortSignal`.
+`SKYFORGE_API_TOKEN` must stay on the server. Never bundle it into frontend
+code.
 
-## Authentication
+## Auth And Security Model
 
-Every request uses the existing Skyforge chat routes and sends:
+The SDK sends:
 
 ```http
-Authorization: Bearer <skyforge_api_token>
+Authorization: Bearer <SKYFORGE_API_TOKEN>
 ```
 
-The SDK does not set cookies, `X-CSRF-Token`, `credentials: "include"`, or call
-`/api/auth/csrf`.
+It does not require browser cookies, CSRF tokens, browser credentials, or
+frontend auth routes.
+
+Use your own app authentication and tenancy checks before deciding which
+Skyforge agent, branch, chat, or `externalId` a request may use. `externalId`
+is metadata for mapping chats back to your app; it is not authentication and it
+does not bypass Skyforge API-token authorization.
+
+## Send a Message
 
-## Response Shape
+```ts
+const response = await skyforge.agentBranches.sendMessage({
+  agentBranchId: process.env.SKYFORGE_AGENT_BRANCH_ID!,
+  message: "Help me plan this outdoor event.",
+  externalId: "event_123",
+  requestId: crypto.randomUUID(),
+});
 
-SDK method inputs use camelCase. Request bodies are serialized to the existing
-backend field names.
+console.log(response.request_id, response.agent_run_id, response.chat_id, response.terminal);
+```
 
-V1 response payloads intentionally mirror the backend DTOs, including snake_case
-fields such as `chat_id`, `agent_branch_id`, and `pending_human_actions`. The SDK
-does not translate response fields to camelCase.
+`externalId` is optional host-app mapping metadata. Use it for values your app
+already understands, such as an event ID, support ticket ID, session ID,
+project ID, or case ID.
 
-## Usage
+When continuing an existing Skyforge chat, pass `chatId`:
 
 ```ts
-import { SkyforgeClient } from "@skyforge-ai/sdk";
+await skyforge.agentBranches.sendMessage({
+  agentBranchId: process.env.SKYFORGE_AGENT_BRANCH_ID!,
+  chatId: "skyforge-chat-id",
+  externalId: "event_123",
+  message: "Summarize the current event status.",
+  structuredContext: {
+    weather: "windy",
+  },
+});
+```
 
-const skyforge = new SkyforgeClient({
-  apiKey: process.env.SKYFORGE_API_TOKEN!,
-  baseUrl: "https://api.skyforge.ai",
+Skyforge may reject a request that tries to continue an existing `chatId` with a
+different `externalId` than the chat already has.
+
+Response fields mirror the Skyforge API payloads and use API field names such
+as `chat_id`, `external_id`, `agent_branch_id`, and `pending_human_actions`.
+
+Every turn is a durable worker-owned run, regardless of the branch's legacy
+runtime mode. `terminal=false` means the HTTP delivery returned before
+execution resolved; preserve `request_id`, `agent_run_id`, and `chat_id` for
+lookup, event replay, and explicit cancellation. Delivery timeout or abort does
+not fail or cancel the run.
+
+## Request Recovery And Cancellation
+
+Use one request ID for one immutable submission contract. An exact retry can
+resolve to the existing run; changing delivery mode or semantic inputs returns
+generic `409 request_id_conflict`.
+
+```ts
+const lookup = await skyforge.agentBranches.lookupRequest({
+  agentBranchId: process.env.SKYFORGE_AGENT_BRANCH_ID!,
+  requestId,
 });
+
+if (!lookup.terminal) {
+  await skyforge.agentRuns.cancel({
+    agentRunId: lookup.agent_run_id,
+    reason: "User requested cancellation",
+  });
+}
 ```
 
-### Get Agent Branch State
+Cancellation is cooperative. It prevents new provider/tool calls after the
+worker observes the request, but cannot undo an already transmitted external
+side effect. Do not translate client disconnect or an SDK `AbortSignal` into a
+cancellation request.
+
+## Recover Chats By External ID
+
+Use `skyforge.chats.list(...)` from your backend to recover chats for an agent.
+The lookup is agent-scoped and can be narrowed to one branch.
 
 ```ts
-const state = await skyforge.agentBranches.getState({
-  agentBranchId: "11111111-1111-1111-1111-111111111111",
-  chatId: "22222222-2222-2222-2222-222222222222",
+const { chats, nextCursor } = await skyforge.chats.list({
+  agentId: process.env.SKYFORGE_AGENT_ID!,
+  externalId: "event_123",
 });
 
-console.log(state.chat_id, state.messages);
+for (const chat of chats) {
+  console.log(chat.chat_id, chat.external_id, chat.agent_branch_name);
+}
+
+console.log(nextCursor);
+```
+
+The SDK calls:
+
+```text
+GET /api/skyforge-chat/agents/{agent_id}/chats
 ```
 
-### Send Message
+Supported query params are `agent_branch_id`, `chat_id`, `external_id`,
+`limit`, and `cursor`. The raw API response field is `next_cursor`; the SDK
+normalizes it to `nextCursor`.
+
+List items include:
+
+- `agent_id`
+- `agent_branch_id`
+- `agent_branch_name`
+- `chat_id`
+- `external_id`
+- `chat_title`
+- `created_at`
+- `updated_at`
+
+## Chat Lookup Examples
+
+Find one known chat:
 
 ```ts
-const response = await skyforge.agentBranches.sendMessage({
-  agentBranchId: "11111111-1111-1111-1111-111111111111",
-  chatId: "22222222-2222-2222-2222-222222222222",
-  message: "Summarize the latest run.",
-  structuredContext: {
-    priority: "high",
-  },
+const { chats } = await skyforge.chats.list({
+  agentId: process.env.SKYFORGE_AGENT_ID!,
+  chatId: "skyforge-chat-id",
 });
 
-console.log(response.chat_id, response.agent_run_id);
+const chat = chats[0];
 ```
 
-### Stream Run Events
+Narrow lookup to one branch:
+
+```ts
+const page = await skyforge.chats.list({
+  agentId: process.env.SKYFORGE_AGENT_ID!,
+  agentBranchId: process.env.SKYFORGE_AGENT_BRANCH_ID!,
+  externalId: "event_123",
+  limit: 20,
+});
+```
+
+Paginate through results:
+
+```ts
+let cursor: string | undefined;
+
+do {
+  const page = await skyforge.chats.list({
+    agentId: process.env.SKYFORGE_AGENT_ID!,
+    externalId: "event_123",
+    cursor,
+  });
+
+  for (const chat of page.chats) {
+    // Render or store the chat mapping in your app.
+    console.log(chat.chat_id, chat.updated_at);
+  }
+
+  cursor = page.nextCursor ?? undefined;
+} while (cursor);
+```
+
+## Build a SaaS Chat History
+
+Use `externalId` when your app already has a record that should own the
+conversation, such as an event, ticket, project, or session. Your backend can
+later call `skyforge.chats.list({ agentId, externalId })` to build a chat
+history or resume-chat experience in your own product.
+
+Skyforge provides the lookup primitive. Your SaaS app still owns the end-user
+history UI, app-level permissions, and the decision about which `externalId` is
+valid for the current user. Treat browser-provided external IDs as metadata,
+not trusted identity.
+
+The public [`Skyforge-AI/api-starter`](https://github.com/Skyforge-AI/api-starter)
+uses `@runmark/sdk` on the backend and `@runmark/agent-chat` in the browser. To
+add a chat-history UI to your own app, call `skyforge.chats.list(...)` from
+your backend and pass the selected `chatId` to the chat component.
+
+## Stream Run Events
 
 ```ts
 const events = await skyforge.agentRuns.streamEvents({
-  agentRunId: "33333333-3333-3333-3333-333333333333",
-  afterSequence: 12,
+  agentRunId: "agent-run-id",
+  afterSequence: 0,
 });
 
 for await (const event of events) {
@@ -83,26 +275,66 @@ for await (const event of events) {
 }
 ```
 
-Breaking out of the loop cancels the underlying response reader.
+Breaking out of the loop cancels the underlying stream reader.
 
-### Submit Human Action
+`afterSequence` is an explicit persisted replay cursor. The low-level SDK does
+not run an infinite reconnect loop or deduplicate events for you; reconnect
+with the last applied sequence and ignore duplicate sequence values in the
+consumer. The parser supports CRLF/chunk boundaries and multiline data, rejects
+malformed or oversized events, and always releases its reader.
+
+## Source References
+
+When Advanced RAG injects labeled sources into an answer, chat messages may
+include `source_references`. These references are safe public metadata for the
+labels visible in the assistant text, such as `[S1]`; they are not the hidden
+RAG prompt or full source documents.
+
+```ts
+const reply = await skyforge.agentBranches.sendMessage({
+  agentBranchId: process.env.SKYFORGE_AGENT_BRANCH_ID!,
+  message: "What does Advanced RAG change?",
+});
+
+for (const message of reply.messages) {
+  for (const source of message.source_references ?? []) {
+    console.log(source.display_label, source.snippet, source.source_type);
+  }
+}
+```
+
+For run-based integrations, source references can also be loaded after the run
+completes:
+
+```ts
+const { source_references } = await skyforge.agentRuns.getSourceReferences({
+  agentRunId: "agent-run-id",
+});
+```
+
+Match references by exact `source_label` or `display_label`, never by array
+position. Source links are not part of the MVP source-reference contract.
+
+## Submit a Human Action
 
 ```ts
 await skyforge.humanActions.submit({
-  humanActionRequestId: "44444444-4444-4444-4444-444444444444",
+  humanActionRequestId: "human-action-request-id",
+  requestId: crypto.randomUUID(),
+  activeOrganizationId: "organization-id",
   values: {
     approved: true,
   },
 });
 ```
 
-### Uploaded Files
+## Upload a Chat File
 
 ```ts
 const upload = await skyforge.uploadedFiles.upload({
-  agentBranchId: "11111111-1111-1111-1111-111111111111",
-  chatId: "22222222-2222-2222-2222-222222222222",
-  file: new Blob(["notes"], { type: "text/plain" }),
+  agentBranchId: process.env.SKYFORGE_AGENT_BRANCH_ID!,
+  chatId: "chat-id",
+  file: new Uint8Array([104, 101, 108, 108, 111]),
   filename: "notes.txt",
   contentType: "text/plain",
 });
@@ -121,99 +353,107 @@ await skyforge.uploadedFiles.delete({
 
 `filename` is required and must not be blank.
 
-## Tests
+## Using With Express
 
-Run the fast SDK unit tests:
+Use your backend as the app proxy for browser chat requests. The browser calls
+your server; your server calls Skyforge with the API token.
 
-```bash
-cd packages/skyforge-sdk
-npm test
-```
+```ts
+import express from "express";
+import { SkyforgeClient } from "@runmark/sdk";
 
-The opt-in live suite requires a running local Skyforge backend and a valid
-local API token with access to the selected agent branch. It uses only
-`Authorization: Bearer <skyforge_api_token>` through the existing
-`/api/skyforge-chat/...` routes.
+const app = express();
+app.use(express.json());
 
-Live test environment variables can be stored in `.e2e.env` at the package
-root. Copy the example file and fill in your local token:
+const skyforge = new SkyforgeClient({
+  apiKey: process.env.SKYFORGE_API_TOKEN!,
+  baseUrl: process.env.SKYFORGE_API_BASE_URL ?? "https://api.skyforge.ai",
+});
 
-```bash
-cd packages/skyforge-sdk
-cp .e2e.env.example .e2e.env
+app.post("/api/skyforge-chat/agent_branches/:agentBranchId/messages", async (req, res, next) => {
+  try {
+    if (req.params.agentBranchId !== process.env.SKYFORGE_AGENT_BRANCH_ID) {
+      res.status(403).json({ error: { message: "Agent branch is not allowed." } });
+      return;
+    }
+
+    const data = await skyforge.agentBranches.sendMessage({
+      agentBranchId: req.params.agentBranchId,
+      chatId: req.body.chat_id,
+      externalId: req.session?.ticketId ?? req.body.external_id,
+      message: req.body.message,
+      structuredContext: req.body.structured_context,
+      retrievalScope: req.body.retrieval_scope,
+    });
+
+    res.json({ message: "ok", data });
+  } catch (error) {
+    next(error);
+  }
+});
 ```
 
-`.e2e.env` is ignored by git. Shell environment variables take precedence over
-values in the file.
+Backend proxies can supply or override `externalId` from trusted app context,
+such as a signed-in user session, event, ticket, project, or case ID. Do not
+treat browser-provided `external_id` as identity.
 
-```bash
-cd packages/skyforge-sdk
-
-SKYFORGE_SDK_LIVE=1 \
-SKYFORGE_API_BASE_URL=http://localhost:3000 \
-SKYFORGE_API_TOKEN=... \
-SKYFORGE_AGENT_BRANCH_ID=... \
-npm run test:live
-```
+## Using With Next.js Route Handlers
 
-With `.e2e.env` populated, this is enough:
+```ts
+import { NextResponse } from "next/server";
+import { SkyforgeClient } from "@runmark/sdk";
 
-```bash
-npm run test:live
-```
+const skyforge = new SkyforgeClient({
+  apiKey: process.env.SKYFORGE_API_TOKEN!,
+  baseUrl: process.env.SKYFORGE_API_BASE_URL ?? "https://api.skyforge.ai",
+});
 
-Optional live test controls:
+export async function POST(request: Request) {
+  const body = await request.json();
+  const data = await skyforge.agentBranches.sendMessage({
+    agentBranchId: process.env.SKYFORGE_AGENT_BRANCH_ID!,
+    chatId: body.chat_id,
+    externalId: body.external_id,
+    message: body.message,
+  });
 
-```bash
-SKYFORGE_SDK_LIVE_UPLOADS=1
-SKYFORGE_SDK_LIVE_HITL_REQUEST_ID=...
-SKYFORGE_SDK_LIVE_EXISTING_CHAT_ID=...
-SKYFORGE_SDK_LIVE_TIMEOUT_MS=60000
-SKYFORGE_SDK_LIVE_HITL_TIMEOUT_MS=120000
-SKYFORGE_SDK_LIVE_EVENT_TIMEOUT_MS=15000
-SKYFORGE_SDK_LIVE_MESSAGE="SDK live smoke test. Reply with a short confirmation."
-SKYFORGE_SDK_LIVE_EXPECT_PENDING_HITL=1
-SKYFORGE_SDK_LIVE_EXPECT_BUBBLED_HITL=1
-SKYFORGE_SDK_LIVE_SUBMIT_PENDING_HITL=1
-SKYFORGE_SDK_LIVE_HITL_VALUES='{"decision":"approve","notes":"Approved by SDK live test."}'
+  return NextResponse.json({ message: "ok", data });
+}
 ```
 
-### HITL Bubbling Demo
+## Error Handling
 
-The repository seed includes a TailYew `hitl-bubbling-demo` parent agent. The
-SDK package has a convenience live command for that seeded local fixture:
+Non-2xx Skyforge API responses throw `SkyforgeApiError`.
 
-```bash
-cd packages/skyforge-sdk
-
-SKYFORGE_API_TOKEN=... \
-npm run test:live:hitl-bubbling-demo
+```ts
+import { SkyforgeApiError } from "@runmark/sdk";
+
+try {
+  await skyforge.agentBranches.getState({
+    agentBranchId: process.env.SKYFORGE_AGENT_BRANCH_ID!,
+  });
+} catch (error) {
+  if (error instanceof SkyforgeApiError) {
+    console.error(error.status, error.code, error.requestId);
+  }
+  throw error;
+}
 ```
 
-If `.e2e.env` contains `SKYFORGE_API_TOKEN`, you can run:
+Avoid logging API tokens, authorization headers, or full request payloads.
 
-```bash
-npm run test:live:hitl-bubbling-demo
-```
+Successful responses must be JSON envelopes with non-null `data`; malformed,
+empty, wrong-content-type, or oversized responses are rejected rather than
+cast to the requested type. Error bodies are bounded before parsing.
 
-This command sets:
+## Compatibility
 
-```bash
-SKYFORGE_SDK_LIVE=1
-SKYFORGE_API_BASE_URL=http://127.0.0.1:3000
-SKYFORGE_AGENT_BRANCH_ID=9ab14d38-55d1-4a9c-bc56-0df2c03aee02
-SKYFORGE_SDK_LIVE_MESSAGE="Use ask_skyforge_agent to ask the human-workflow-demo child agent to look up Bulbasaur. Do not answer without calling the child agent."
-SKYFORGE_SDK_LIVE_TIMEOUT_MS=180000
-SKYFORGE_SDK_LIVE_HITL_TIMEOUT_MS=120000
-SKYFORGE_SDK_LIVE_EVENT_TIMEOUT_MS=15000
-SKYFORGE_SDK_LIVE_EXPECT_PENDING_HITL=1
-SKYFORGE_SDK_LIVE_EXPECT_BUBBLED_HITL=1
-SKYFORGE_SDK_LIVE_SUBMIT_PENDING_HITL=1
-```
-
-`SKYFORGE_API_TOKEN` is still required and is not set by the script. Use a valid
-local API token with access to the seeded TailYew repository/branch. You can
-override the base URL, branch ID, message, HITL values, or timeout by setting
-the same environment variables before running the command.
-
-Do not expose Skyforge API tokens in browser code. This SDK is server-side only.
+The durable request-ID, lookup, cancellation, and HITL correlation APIs are
+additive in `0.1.2`. Existing callers may omit request IDs, but embedded and
+retry-sensitive integrations should supply them. The SDK remains server-only
+and throws if constructed in a browser environment.
+
+## Related Package
+
+Use `@runmark/agent-chat` for the browser and React chat UI. Keep this SDK on
+the backend and expose only the app-specific proxy routes your frontend needs.

package/dist/client.d.ts

@@ -1,15 +1,41 @@
-import type { DeleteUploadedFileParams, GetAgentBranchStateParams, SendMessageParams, SkyforgeAgentRunEventEnvelope, SkyforgeChatMessageResponse, SkyforgeChatStateResponse, SkyforgeChatUploadedFileListResponse, SkyforgeChatUploadedFileUploadResponse, SkyforgeClientOptions, StreamAgentRunEventsParams, SubmitHumanActionParams, UploadFileParams, ListUploadedFilesParams } from "./types.js";
+import type { CancelAgentRunParams, CancelAgentRunResponse, CreateWebhookEndpointParams, CreateWebhookReplayParams, DeleteUploadedFileParams, GetAgentRunSourceReferencesParams, GetAgentRunParams, GetAgentBranchStateParams, GetRepositoryWebhookDeliveryParams, ListChatsParams, ListWebhookAttemptsParams, ListWebhookDeliveriesParams, ListWebhookEndpointsParams, ListRepositoryWebhookDeliveriesParams, ListUploadedFilesParams, LookupAgentRunRequestParams, SendMessageParams, SkyforgeAgentRunEventEnvelope, SkyforgeAgentRunRequestLookupResponse, SkyforgeChatSourceReferencesResponse, SkyforgeChatListResponse, SkyforgeChatMessageResponse, SkyforgeChatStateResponse, SkyforgeChatUploadedFileListResponse, SkyforgeChatUploadedFileUploadResponse, SkyforgeClientOptions, StreamAgentRunEventsParams, SubmitHumanActionParams, GetHumanActionParams, HumanActionRequestDto, JsonObject, RepositoryWebhookDeliveryDetail, RepositoryWebhookDeliveryListResponse, UpdateWebhookEndpointParams, WebhookAttemptListResponse, WebhookDeliveryListResponse, WebhookEndpointHealth, WebhookEndpointParams, WebhookEndpointSecretResponse, WebhookEndpointSummary, WebhookReplaySummary, WebhookTestDeliveryResponse, UploadFileParams } from "./types.js";
 export declare class SkyforgeClient {
     readonly agentBranches: {
         getState: (params: GetAgentBranchStateParams) => Promise<SkyforgeChatStateResponse>;
         sendMessage: (params: SendMessageParams) => Promise<SkyforgeChatMessageResponse>;
+        lookupRequest: (params: LookupAgentRunRequestParams) => Promise<SkyforgeAgentRunRequestLookupResponse>;
+    };
+    readonly chats: {
+        list: (params: ListChatsParams) => Promise<SkyforgeChatListResponse>;
     };
     readonly agentRuns: {
+        get: (params: GetAgentRunParams) => Promise<JsonObject>;
         streamEvents: (params: StreamAgentRunEventsParams) => Promise<AsyncIterable<SkyforgeAgentRunEventEnvelope>>;
+        getSourceReferences: (params: GetAgentRunSourceReferencesParams) => Promise<SkyforgeChatSourceReferencesResponse>;
+        cancel: (params: CancelAgentRunParams) => Promise<CancelAgentRunResponse>;
     };
     readonly humanActions: {
+        get: (params: GetHumanActionParams) => Promise<HumanActionRequestDto>;
         submit: (params: SubmitHumanActionParams) => Promise<SkyforgeChatMessageResponse>;
     };
+    readonly webhooks: {
+        create: (params: CreateWebhookEndpointParams) => Promise<WebhookEndpointSecretResponse>;
+        list: (params: ListWebhookEndpointsParams) => Promise<WebhookEndpointSummary[]>;
+        get: (params: WebhookEndpointParams) => Promise<WebhookEndpointSummary>;
+        update: (params: UpdateWebhookEndpointParams) => Promise<WebhookEndpointSummary>;
+        delete: (params: WebhookEndpointParams) => Promise<string>;
+        enable: (params: WebhookEndpointParams) => Promise<WebhookEndpointSummary>;
+        disable: (params: WebhookEndpointParams) => Promise<WebhookEndpointSummary>;
+        rotateSecret: (params: WebhookEndpointParams) => Promise<WebhookEndpointSecretResponse>;
+        test: (params: WebhookEndpointParams) => Promise<WebhookTestDeliveryResponse>;
+        health: (params: WebhookEndpointParams) => Promise<WebhookEndpointHealth>;
+        listDeliveries: (params: ListWebhookDeliveriesParams) => Promise<WebhookDeliveryListResponse>;
+        listAttempts: (params: ListWebhookAttemptsParams) => Promise<WebhookAttemptListResponse>;
+        listRepositoryDeliveries: (params: ListRepositoryWebhookDeliveriesParams) => Promise<RepositoryWebhookDeliveryListResponse>;
+        getDelivery: (params: GetRepositoryWebhookDeliveryParams) => Promise<RepositoryWebhookDeliveryDetail>;
+        replay: (params: CreateWebhookReplayParams) => Promise<WebhookReplaySummary>;
+        listReplays: (params: WebhookEndpointParams) => Promise<WebhookReplaySummary[]>;
+    };
     readonly uploadedFiles: {
         list: (params: ListUploadedFilesParams) => Promise<SkyforgeChatUploadedFileListResponse>;
         upload: (params: UploadFileParams) => Promise<SkyforgeChatUploadedFileUploadResponse>;
@@ -18,9 +44,30 @@ export declare class SkyforgeClient {
     private readonly baseUrl;
     private readonly http;
     constructor(options: SkyforgeClientOptions);
+    private getAgentRun;
+    private getHumanAction;
+    private createWebhookEndpoint;
+    private listWebhookEndpoints;
+    private getWebhookEndpoint;
+    private updateWebhookEndpoint;
+    private deleteWebhookEndpoint;
+    private webhookEndpointAction;
+    private rotateWebhookSecret;
+    private testWebhookEndpoint;
+    private getWebhookHealth;
+    private listWebhookDeliveries;
+    private listWebhookAttempts;
+    private listRepositoryWebhookDeliveries;
+    private getRepositoryWebhookDelivery;
+    private replayWebhookEvents;
+    private listWebhookReplays;
     private getAgentBranchState;
+    private listChats;
     private sendMessage;
+    private lookupRequest;
     private streamEvents;
+    private getSourceReferences;
+    private cancelAgentRun;
     private submitHumanAction;
     private listUploadedFiles;
     private uploadFile;