ql-agent-sdk 1.3.3 → 1.4.1

package/README.md

@@ -78,7 +78,7 @@ Create keys in your Quanton Labs dashboard → **API Keys** page. Each key is sc
 | `agents` | `ql.agents.list()`, `ql.agents.get()` |
 | `capabilities` | `ql.agents.capabilities()`, `ql.agents.runCapability()` |
 | `chat` | `ql.agents.chat()`, `ql.agents.chatStream()` |
-| `messages` | `ql.agents.history()` |
+| `messages` | `ql.agents.history()`, `ql.agents.listMessages()` |
 | `workflows` | `ql.workflows.run()`, `ql.workflows.getRun()` |
 | `tasks` | `ql.tasks.create()`, `ql.tasks.get()` |
 | `*` | All of the above (default for new keys) |
@@ -485,6 +485,74 @@ do {
 console.log(`${allMessages.length} total messages`);
 ```
 
+#### `ql.agents.listMessages(params)` → `Promise<AgentMessagesPage>`
+
+**Scope:** `messages`
+
+Returns the **chronological message feed** for a conversation — chat turns plus workflow artifacts (tool results, step progress, approval requests). Use this to poll live progress of a background run: call it without `after` for the latest N, then page forward with `after`.
+
+**Parameters:**
+- `params.agentId: string` — agent slug or ObjectId (required)
+- `params.after?: string` — cursor = id of the last item you received (forward pagination). Omit for the latest N.
+- `params.limit?: number` — page size, 1–50 (default 20)
+- `params.userId?: string` — optional filter by user (defaults to the workspace id)
+
+**Response (200):**
+```json
+{
+  "items": [
+    {
+      "id": "6ae0d963...",
+      "role": "user",
+      "kind": "chat",
+      "content": "Import this CSV into users",
+      "status": "completed",
+      "timestamp": "2026-11-05T10:00:00.000Z"
+    },
+    {
+      "id": "6ae0d964...",
+      "role": "assistant",
+      "kind": "workflow",
+      "content": null,
+      "taskId": "6ae0d965...",
+      "toolCalls": [{ "name": "fetch_schema", "status": "completed", "result": { "collections": ["users"] } }],
+      "status": "completed",
+      "timestamp": "2026-11-05T10:00:02.000Z"
+    },
+    {
+      "id": "6ae0d966...",
+      "role": "assistant",
+      "kind": "approval_request",
+      "content": "Delete 3 rows from `users`? ...",
+      "outputFormat": "json",
+      "status": "completed",
+      "timestamp": "2026-11-05T10:00:05.000Z"
+    }
+  ],
+  "hasMore": true,
+  "nextAfter": "6ae0d966..."
+}
+```
+
+| Field | Description |
+|-------|-------------|
+| `items[].kind` | `"chat"` (default), `"tool_result"`, `"workflow"`, or `"approval_request"` |
+| `items[].content` | Message text (may be null for artifact-only entries) |
+| `items[].outputFormat` | Declared format of `content`: `"text"`, `"json"`, or `"html"` |
+| `items[].toolCalls` | Tool invocations; each may carry a truncated `result` once complete |
+| `items[].taskId` | Task id for entries produced by a background workflow run |
+| `hasMore` / `nextAfter` | Forward pagination: pass `nextAfter` as the next `after` |
+
+**Polling a live run (e.g. every 4s):**
+```ts
+let after: string | undefined;
+const timer = setInterval(async () => {
+  const page = await ql.agents.listMessages({ agentId: "operations", limit: 20, after });
+  for (const item of page.items) renderFeedItem(item); // tool chips, step progress, approvals…
+  after = page.nextAfter;
+}, 4000);
+```
+
 ---
 
 ### Workflows
@@ -799,6 +867,118 @@ const uploaded = await ql.files.upload(new Blob([blob], { type: "video/mp4" }),
 });
 ```
 
+### Architecture (Approvals · Policies · Events · Subagents · Skills · Executions)
+
+The platform enforces a policy engine over every protected action (agent tool calls, workflow
+nodes, skill runs, subagent tools). Protected actions that are not fully autonomous produce an
+**approval request**; approved actions execute exactly once. All of this is observable and
+controllable through the namespaces below. List endpoints return *list-safe* views (no bound
+payloads); detail endpoints include full records.
+
+#### `ql.approvals.list(params?)` → `Promise<ApprovalsListResult>`
+
+**Scope:** `approvals`
+
+Lists approval requests, newest first. `params?: { status?: ApprovalStatus[], limit?, beforeCreatedAt?: string | Date }`
+— statuses: `pending`, `approved`, `rejected`, `expired`, `consumed`.
+
+#### `ql.approvals.get(approvalId)` → `Promise<ApprovalDetail>`
+
+**Scope:** `approvals`
+
+Full record including the bound action payload, evaluation (rule pack / rule / severity / reason),
+evidence, and decision metadata.
+
+#### `ql.approvals.decide(approvalId, input)` → `Promise<DecideApprovalResult>`
+
+**Scope:** `approvals`
+
+Records an authorized workspace member's decision. `input: { decision: "approve" | "reject", decidedBy, note?, evidence? }`.
+A user cannot approve their own request (403). State errors (pending/expired/consumed/…) → 409; unknown id → 404.
+
+#### `ql.approvals.execute(approvalId)` → `Promise<ExecuteApprovalResult>`
+
+**Scope:** `approvals`
+
+Executes the bound action of an approved approval, consuming it atomically (no replays).
+Returns `{ ok, approvalId, action, status: "consumed", result?, error? }` — executor failures return
+`ok: false` with the error while the approval is still consumed.
+
+#### `ql.policies.get()` → `Promise<PoliciesResult>`
+
+**Scope:** `policies`
+
+Returns active rule packs with their rules, the documented roadmap client packs (registered but
+inactive), and honest stats `{ total, active, roadmap, rulesTotal }`.
+
+#### `ql.events.list(params?)` → `Promise<EventsPage>`
+
+**Scope:** `events`
+
+Paginated read of the hash-chained audit ledger, newest first. `params?: { limit?, beforeSeq?, types?: string[] }`.
+Returns `{ items, hasMore, nextBeforeSeq?, total? }` — walk pages by passing `nextBeforeSeq` back as `beforeSeq`.
+
+#### `ql.events.verify(params?)` → `Promise<VerifyChainResult>`
+
+**Scope:** `events`
+
+Recomputes every event hash and checks each `prevHash` link over the window `seq <= afterSeq`
+(all events when omitted). Returns `{ valid, checkedCount, firstBadSeq?, reason? }`.
+
+#### `ql.events.retention()` → `Promise<RetentionReport>`
+
+**Scope:** `events`
+
+Retention report: `{ retentionDays: 365, oldestEventAt?, eventsInsideRetentionWindow,
+eventsOutsideRetentionWindow, autoDeletionEnabled: false, note }`. No automatic deletion runs.
+
+#### `ql.subagents.list(agentId?)` → `Promise<SubagentsListResult>`
+
+**Scope:** `subagents`
+
+Specialist definitions owned by the eight catalog agents (optionally filtered by owner) plus honest
+stats `{ total, enabled, disabled, withHttp, byAgent }`. 54 definitions ship; 4 permit `http_request`.
+
+#### `ql.subagents.get(subagentId)` → `Promise<SubagentDefinition>`
+
+**Scope:** `subagents`
+
+One definition: permitted tools, I/O contracts, execution constraints, applicability notes.
+
+#### `ql.skills.list(domain?)` → `Promise<SkillsListResult>`
+
+**Scope:** `skills`
+
+Skill definitions (no implementation functions) plus honest stats `{ total, readOnly, write, enabled, byDomain }`.
+3 skills ship, all read-class and enabled.
+
+#### `ql.skills.get(skillId)` → `Promise<SkillDefinition>`
+
+**Scope:** `skills`
+
+One definition: I/O contract, execution class, version, description.
+
+#### `ql.skills.run(input)` → `Promise<SkillRunResult>`
+
+**Scope:** `skills`
+
+Runs a skill through validation → authorization → policy → audit → execution.
+`input: { skillId, input: Record<string, unknown>, actorUserId, idempotencyKey? }`.
+Unknown/disabled skills → 404; invalid or oversized input → 400.
+
+#### `ql.executions.list(params?)` → `Promise<ExecutionsListResult>`
+
+**Scope:** `executions`
+
+Execution history (list-safe views). `params?: { agentId?, status?: ExecutionStatus[], limit?, beforeCreatedAt?: string | Date }`.
+
+#### `ql.executions.get(executionId)` → `Promise<ExecutionDetail>`
+
+**Scope:** `executions`
+
+Full trace: ordered tool calls (seq, toolName, ok, durationMs, error, approvalId, ledgerSeq), token
+usage, approval/ledger back-references, and direct child executions (subagent runs).
+
 ---
 
 ## Error Handling
@@ -969,18 +1149,18 @@ export async function POST(req: Request) {
 
 ## Agent Reference
 
-The platform includes 8 specialized agents. Each has 20 capabilities in its domain:
-
-| ID | Domain | Examples |
-|----|--------|----------|
-| `governing` | Orchestration | Coordinates other agents, complex multi-step reasoning |
-| `finance` | Finance | Invoices, P&L, budgeting, cash flow, tax estimates |
-| `marketing` | Marketing | Social media content, ad copy, SEO, campaign planning |
-| `inventory` | Supply Chain | Stock levels, reorder points, supplier management |
-| `customer` | Customer Success | Support drafts, onboarding sequences, churn analysis |
-| `developer` | Engineering | Code generation, API docs, bug triage, test writing |
-| `operations` | Operations | SOPs, process mapping, KPI dashboards, compliance |
-| `research` | Research | Market analysis, competitor intel, literature reviews |
+The platform includes 8 specialized agents:
+
+| ID | Domain | Role |
+|----|--------|------|
+| `governing` | Orchestration | The orchestrator: reasons over the goal, plans execution, dispatches subtasks to the other agents (and specialist subagents), and synthesizes the final answer |
+| `marketing` | Marketing & Content | Plans, creates, distributes, and optimizes content across all channels |
+| `sales` | Sales | Manages the revenue pipeline from inbound lead to closed deal |
+| `cx` | Customer Experience | Post-acquisition service, retention, and support quality |
+| `people` | People & Team | Employee lifecycle: hiring, onboarding, performance, scheduling |
+| `operations` | Operations | Internal execution infrastructure: tasks, SOPs, vendors, QA |
+| `inventory` | Inventory & Supply Chain | Stock levels, suppliers, reorder logic, delivery tracking |
+| `finance` | Finance | Invoices, P&L, cash flow, budgets, financial reporting |
 
 Discover available capabilities at runtime:
 ```ts

package/dist/index.cjs

@@ -21,13 +21,21 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var index_exports = {};
 __export(index_exports, {
   API_ERROR_CODES: () => API_ERROR_CODES,
+  APPROVAL_STATUSES: () => APPROVAL_STATUSES,
   AgentsApi: () => AgentsApi,
+  ApprovalsApi: () => ApprovalsApi,
   AudioApi: () => AudioApi,
   DEFAULT_BASE_URL: () => DEFAULT_BASE_URL,
+  EXECUTION_STATUSES: () => EXECUTION_STATUSES,
+  EventsApi: () => EventsApi,
+  ExecutionsApi: () => ExecutionsApi,
   FilesApi: () => FilesApi,
   ImagesApi: () => ImagesApi,
+  PoliciesApi: () => PoliciesApi,
   QLClient: () => QLClient,
   QLError: () => QLError,
+  SkillsApi: () => SkillsApi,
+  SubagentsApi: () => SubagentsApi,
   TaskHandle: () => TaskHandle,
   TasksApi: () => TasksApi,
   VideoTaskHandle: () => VideoTaskHandle,
@@ -517,6 +525,18 @@ var AgentsApi = class {
       query: { limit: params.limit, before: params.before, userId: params.userId }
     });
   }
+  /**
+   * GET /api/v1/agents/messages — chronological message feed for a conversation.
+   *
+   * Returns the latest N entries in chronological order (omit `after`), or page
+   * forward with `after` = id of the last item you received. Includes workflow
+   * artifacts: tool results, step progress, and approval requests.
+   */
+  listMessages(params) {
+    return this.t.json("GET", "/api/v1/agents/messages", {
+      query: { agentId: params.agentId, after: params.after, limit: params.limit, userId: params.userId }
+    });
+  }
   async *chatStreamImpl(input, opts) {
     const body = await this.t.stream("POST", "/api/v1/agents/chat/stream", { body: input, signal: opts.signal });
     let content = "";
@@ -637,6 +657,115 @@ var FilesApi = class {
     return result;
   }
 };
+var ApprovalsApi = class {
+  constructor(t) {
+    this.t = t;
+  }
+  /** GET /api/v1/approvals — list policy approval requests (list-safe views, no payload). */
+  list(params) {
+    return this.t.json("GET", "/api/v1/approvals", {
+      query: {
+        status: params?.status?.join(","),
+        limit: params?.limit,
+        beforeCreatedAt: toIso(params?.beforeCreatedAt)
+      }
+    });
+  }
+  /** GET /api/v1/approvals/:id — full approval record incl. bound payload + evidence. */
+  get(approvalId) {
+    return this.t.json("GET", `/api/v1/approvals/${encodeURIComponent(approvalId)}`);
+  }
+  /** POST /api/v1/approvals/:id/decide — record an authorized workspace member's decision. */
+  decide(approvalId, input) {
+    return this.t.json("POST", `/api/v1/approvals/${encodeURIComponent(approvalId)}/decide`, { body: input });
+  }
+  /** POST /api/v1/approvals/:id/execute — execute the bound action of an approved approval, exactly once. */
+  execute(approvalId) {
+    return this.t.json("POST", `/api/v1/approvals/${encodeURIComponent(approvalId)}/execute`);
+  }
+};
+var PoliciesApi = class {
+  constructor(t) {
+    this.t = t;
+  }
+  /** GET /api/v1/policies — active rule packs with their rules + documented roadmap packs. */
+  get() {
+    return this.t.json("GET", "/api/v1/policies");
+  }
+};
+var EventsApi = class {
+  constructor(t) {
+    this.t = t;
+  }
+  /** GET /api/v1/events — paginated ledger read, newest first (`beforeSeq` pages backwards). */
+  list(params) {
+    return this.t.json("GET", "/api/v1/events", {
+      query: { limit: params?.limit, beforeSeq: params?.beforeSeq, types: params?.types?.join(",") }
+    });
+  }
+  /** GET /api/v1/events/verify — recompute every hash and check each prevHash link (audit retrieval). */
+  verify(params) {
+    return this.t.json("GET", "/api/v1/events/verify", { query: { afterSeq: params?.afterSeq } });
+  }
+  /** GET /api/v1/events/retention — retention report (no automatic deletion runs). */
+  retention() {
+    return this.t.json("GET", "/api/v1/events/retention");
+  }
+};
+var SubagentsApi = class {
+  constructor(t) {
+    this.t = t;
+  }
+  /** GET /api/v1/subagents — specialist definitions + honest stats (optionally filtered by owning agent). */
+  list(agentId) {
+    return this.t.json("GET", "/api/v1/subagents", { query: { agentId } });
+  }
+  /** GET /api/v1/subagents/:id — one specialist definition. */
+  get(subagentId) {
+    return this.t.json("GET", `/api/v1/subagents/${encodeURIComponent(subagentId)}`);
+  }
+};
+var SkillsApi = class {
+  constructor(t) {
+    this.t = t;
+  }
+  /** GET /api/v1/skills — skill definitions (no implementation functions) + honest stats. */
+  list(domain) {
+    return this.t.json("GET", "/api/v1/skills", { query: { domain } });
+  }
+  /** GET /api/v1/skills/:id — one skill definition. */
+  get(skillId) {
+    return this.t.json("GET", `/api/v1/skills/${encodeURIComponent(skillId)}`);
+  }
+  /** POST /api/v1/skills/run — run a skill through the full validation → authorization → policy → audit → execution pipeline. */
+  run(input) {
+    return this.t.json("POST", "/api/v1/skills/run", { body: input });
+  }
+};
+var ExecutionsApi = class {
+  constructor(t) {
+    this.t = t;
+  }
+  /** GET /api/v1/executions — execution history (list-safe views, no tool-call log). */
+  list(params) {
+    return this.t.json("GET", "/api/v1/executions", {
+      query: {
+        agentId: params?.agentId,
+        status: params?.status?.join(","),
+        limit: params?.limit,
+        beforeCreatedAt: toIso(params?.beforeCreatedAt)
+      }
+    });
+  }
+  /** GET /api/v1/executions/:id — full execution trace incl. tool calls + direct children. */
+  get(executionId) {
+    return this.t.json("GET", `/api/v1/executions/${encodeURIComponent(executionId)}`);
+  }
+};
+function toIso(value) {
+  if (value === void 0) return void 0;
+  return value instanceof Date ? value.toISOString() : value;
+}
 function readEnvBaseUrl() {
   try {
     if (typeof process !== "undefined" && process?.env) {
@@ -661,6 +790,12 @@ var QLClient = class {
     this.images = new ImagesApi(this.transport);
     this.videos = new VideosApi(this.transport);
     this.audio = new AudioApi(this.transport);
+    this.approvals = new ApprovalsApi(this.transport);
+    this.policies = new PoliciesApi(this.transport);
+    this.events = new EventsApi(this.transport);
+    this.subagents = new SubagentsApi(this.transport);
+    this.skills = new SkillsApi(this.transport);
+    this.executions = new ExecutionsApi(this.transport);
     this.files = new FilesApi(this.transport);
   }
   /** The normalized base URL in use (not secret). */
@@ -678,4 +813,14 @@ var API_ERROR_CODES = {
   conflict: "conflict",
   internalError: "internal_error"
 };
+var APPROVAL_STATUSES = [
+  "pending",
+  "approved",
+  "rejected",
+  "expired",
+  "consumed",
+  "invalidated",
+  "cancelled"
+];
+var EXECUTION_STATUSES = ["running", "completed", "failed", "cancelled", "timeout"];
 //# sourceMappingURL=index.cjs.map