ql-agent-sdk 1.4.0 → 1.4.1

package/README.md

@@ -867,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
@@ -1037,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,
@@ -649,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) {
@@ -673,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). */
@@ -690,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