@qodo/sdk 0.13.3 → 2.0.0-next.0

package/dist/qar/specs.js

@@ -0,0 +1,29 @@
+/**
+ * Wire types for `task.start { agent: InlineAgentSpec }` (Pattern B) and
+ * `task.start { graph: InlineGraphSpec }` (Pattern C) — also accepted by
+ * `client.specs.validate(spec)` for pre-wire validation.
+ *
+ * **Naming.** The public symbol `AgentSpec` is owned by `QarRegistryClient`
+ * as the *local-registry* agent shape (simple `name` + `instructions` +
+ * tool strings). The `Inline*`-prefixed types here are the *wire* shape
+ * — what flows on the network to QAR's `task.start` and
+ * `POST /v1/specs/validate`. Two different layers, two different types,
+ * kept orthogonal so consumers writing local agents and consumers
+ * writing inline specs don't have to share a single struct trying to
+ * span both.
+ *
+ * Field names match QAR's wire vocabulary verbatim — `apiVersion`,
+ * `instructions` (not `system_prompt`), `tools: FunctionToolDef[]`
+ * (not `{ name }`-refs), `kind: 'AgentSpec'` (the discriminator the
+ * validator routes on; matches QAR's `SPEC_KIND_AGENT`).
+ *
+ * Rule-checking lives at QAR's `qar.specs.validator.validate_spec_payload`
+ * — single source of truth shared between `POST /v1/specs/validate` and
+ * `_handle_task_start`. Client-side, pre-wire
+ * `assertInlineAgentSpecPreWire` (see `TaskClient`) rejects the obvious
+ * forbidden-key cases at intake so the consumer's stack trace points at
+ * their call site instead of a `task.done(failed)` arriving over the
+ * wire.
+ */
+export {};
+//# sourceMappingURL=specs.js.map

package/dist/qar/specs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"specs.js","sourceRoot":"","sources":["../../src/qar/specs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG"}

package/dist/qar/taskEvents.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `TaskEvent` — the canonical streaming primitive consumers iterate over.
+ *
+ * It's the subset of `Envelope` that surfaces from `client.tasks.start()` /
+ * `tasks.continue()` / `tasks.resubscribe()` as `AsyncIterable<TaskEvent>`,
+ * plus the SDK-internal `qar.client.*` lifecycle events surfaced on the
+ * same iterator. The `kind` discriminator is identical to the
+ * underlying envelope so consumers can `switch (event.kind)` without
+ * translation.
+ *
+ * Excludes pure client-to-server kinds (`task.start`, `task.continue`,
+ * `task.cancel`, `task.resubscribe`, `tool.response`) — those are produced by
+ * SDK methods, not consumed from them.
+ *
+ * The synthetic `qar.client.*` arms are NOT QAR envelopes; they have no
+ * `message_id` / `session_id` / `payload`. The namespace prefix prevents
+ * collision with any current or future server-side discriminant. Consumers
+ * who don't care about reconnect signal can ignore them — TypeScript narrows
+ * them out of any `case 'task.delta':` branch automatically.
+ */
+import type { TaskDeltaEnvelope, TaskDoneEnvelope, ToolRequestEnvelope, StateUpdateEnvelope, AgentSpawnEnvelope, BulletinPostEnvelope, ArtifactAddEnvelope, FlowPauseEnvelope, FlowResumeEnvelope, ErrorEnvelope } from './envelopes.js';
+import type { ClientEvent } from './clientEvents.js';
+export type TaskEvent = TaskDeltaEnvelope | TaskDoneEnvelope | ToolRequestEnvelope | StateUpdateEnvelope | AgentSpawnEnvelope | BulletinPostEnvelope | ArtifactAddEnvelope | FlowPauseEnvelope | FlowResumeEnvelope | ErrorEnvelope | ClientEvent;
+export type TaskEventKind = TaskEvent['kind'];
+//# sourceMappingURL=taskEvents.d.ts.map

package/dist/qar/taskEvents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"taskEvents.d.ts","sourceRoot":"","sources":["../../src/qar/taskEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,mBAAmB,EACnB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACd,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD,MAAM,MAAM,SAAS,GACjB,iBAAiB,GACjB,gBAAgB,GAChB,mBAAmB,GACnB,mBAAmB,GACnB,kBAAkB,GAClB,oBAAoB,GACpB,mBAAmB,GACnB,iBAAiB,GACjB,kBAAkB,GAClB,aAAa,GACb,WAAW,CAAC;AAEhB,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC"}

package/dist/qar/taskEvents.js

@@ -0,0 +1,22 @@
+/**
+ * `TaskEvent` — the canonical streaming primitive consumers iterate over.
+ *
+ * It's the subset of `Envelope` that surfaces from `client.tasks.start()` /
+ * `tasks.continue()` / `tasks.resubscribe()` as `AsyncIterable<TaskEvent>`,
+ * plus the SDK-internal `qar.client.*` lifecycle events surfaced on the
+ * same iterator. The `kind` discriminator is identical to the
+ * underlying envelope so consumers can `switch (event.kind)` without
+ * translation.
+ *
+ * Excludes pure client-to-server kinds (`task.start`, `task.continue`,
+ * `task.cancel`, `task.resubscribe`, `tool.response`) — those are produced by
+ * SDK methods, not consumed from them.
+ *
+ * The synthetic `qar.client.*` arms are NOT QAR envelopes; they have no
+ * `message_id` / `session_id` / `payload`. The namespace prefix prevents
+ * collision with any current or future server-side discriminant. Consumers
+ * who don't care about reconnect signal can ignore them — TypeScript narrows
+ * them out of any `case 'task.delta':` branch automatically.
+ */
+export {};
+//# sourceMappingURL=taskEvents.js.map

package/dist/qar/taskEvents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"taskEvents.js","sourceRoot":"","sources":["../../src/qar/taskEvents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/dist/qar/trace.d.ts

@@ -0,0 +1,12 @@
+/**
+ * W3C Trace Context type — re-exported from the codegen.
+ *
+ * Source: QAR's `protocol.envelopes.TraceContext` Pydantic model. The codegen
+ * picks up the `traceparent` (required, 55-char `00-<32hex>-<16hex>-<2hex>`
+ * per https://www.w3.org/TR/trace-context/) and `tracestate` (optional vendor
+ * data) constraints. QAR enforces the 55-char regex server-side; the SDK
+ * trusts inbound on parse and produces valid headers outbound via the
+ * OTel layer.
+ */
+export type { TraceContext } from './generated/envelope.js';
+//# sourceMappingURL=trace.d.ts.map

package/dist/qar/trace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.d.ts","sourceRoot":"","sources":["../../src/qar/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,YAAY,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC"}

package/dist/qar/trace.js

@@ -0,0 +1,12 @@
+/**
+ * W3C Trace Context type — re-exported from the codegen.
+ *
+ * Source: QAR's `protocol.envelopes.TraceContext` Pydantic model. The codegen
+ * picks up the `traceparent` (required, 55-char `00-<32hex>-<16hex>-<2hex>`
+ * per https://www.w3.org/TR/trace-context/) and `tracestate` (optional vendor
+ * data) constraints. QAR enforces the 55-char regex server-side; the SDK
+ * trusts inbound on parse and produces valid headers outbound via the
+ * OTel layer.
+ */
+export {};
+//# sourceMappingURL=trace.js.map

package/dist/qar/trace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace.js","sourceRoot":"","sources":["../../src/qar/trace.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/skills/activation.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Skills activation pipeline.
+ *
+ * Renders the **active-skill block** that lands in the wire `instructions`
+ * field above the slim-index block whenever the SDK has any caller-pinned
+ * skills to activate. The block is the on-the-wire shape of "this skill's
+ * body is loaded into the conversation and authoritative for the rest of
+ * the run".
+ *
+ * Inputs: a manager, a list of pinned `ParsedSkill`s (in pin order), and
+ * the resolved trust + caps state from `SkillsManager`.
+ *
+ * Outputs: rendered text + telemetry events. Pure — no side effects; the
+ * caller forwards events to the configured sink and decides what to do
+ * with the text.
+ *
+ * `requires:` resolution lives here too — caller-pin activation is the
+ * one path where the SDK resolves a transitive requires graph eagerly
+ * (the MCP server's `get_skill` handler does the same for LLM-driven
+ * activation, sharing the same helper functions).
+ *
+ * Per `skills-activation.md` §2 the block contract:
+ *
+ *   - One `<active_skill: fqn>` ... `</active_skill>` per skill, in
+ *     resolution order (deps before dependents).
+ *   - Combined body text is wrapped in `<active_skills>` so the renderer
+ *     can defensively close the block at a single known footer regardless
+ *     of what skill authors put in their bodies.
+ *   - A preamble warns the model the entries are authoritative skill
+ *     bodies, distinct from the *advisory* `<available_skills>` index
+ *     that follows.
+ */
+import type { ResolvedRequiresCaps, SkillsManager } from './manager.js';
+import type { ParsedSkill, SkillEvent } from './types.js';
+/**
+ * Resolved activation graph for one caller-pinned root. Carries every
+ * `ParsedSkill` that should be activated (root + transitive `requires`),
+ * in body-injection order (deps first, root last).
+ */
+export interface ActivationGraph {
+    readonly root: ParsedSkill;
+    readonly ordered: readonly ParsedSkill[];
+}
+/**
+ * Outcome of `resolveActivationGraph` for one root.
+ */
+export type ActivationGraphResult = {
+    readonly outcome: 'ok';
+    readonly graph: ActivationGraph;
+} | {
+    readonly outcome: 'requires_trust_violation';
+    readonly child: ParsedSkill;
+    readonly reason: string;
+} | {
+    readonly outcome: 'requires_cap_exceeded';
+    readonly kind: 'depth' | 'breadth' | 'token_budget';
+    readonly limit: number;
+    readonly actual: number;
+} | {
+    readonly outcome: 'requires_cycle';
+    readonly fqn: string;
+} | {
+    readonly outcome: 'requires_unresolved';
+    readonly specifier: string;
+};
+/**
+ * Synchronous lookup adapter the resolver uses to walk a `requires:`
+ * chain. Both call sites (the SDK's caller-pin path and the MCP server's
+ * `get_skill` LLM-driven path) build one of these from an already-loaded
+ * catalog snapshot — the catalog is `discover()`'d once at connect time,
+ * so the lookup itself is always sync.
+ */
+export interface SkillLookup {
+    get(specifier: string): ParsedSkill | null;
+    isTrusted(skill: ParsedSkill): boolean;
+    readonly caps: ResolvedRequiresCaps;
+}
+/**
+ * Build a sync `SkillLookup` from an already-loaded catalog snapshot
+ * plus a `SkillsManager` (for trust + caps). Callers acquire the
+ * snapshot via `await manager.discover()` (or `manager.currentSnapshot`
+ * when already present) before constructing the lookup.
+ */
+export declare function lookupFromSnapshot(skills: readonly ParsedSkill[], manager: SkillsManager): SkillLookup;
+/**
+ * Resolve a single root skill's `requires:` chain with the depth /
+ * breadth / token caps applied. Trust is enforced transitively per
+ * `skills-trust.md` §3.
+ *
+ * The resolver runs *before* any body injection — if any check fails,
+ * the result carries a `non-ok` outcome and the caller never composes
+ * a partial body block.
+ */
+export declare function resolveActivationGraph(root: ParsedSkill, lookup: SkillLookup): ActivationGraphResult;
+/**
+ * Resolution outcome for a multi-pin activation. `ok` carries the
+ * combined ordered list (deps first, dependents next) with duplicates
+ * deduplicated by FQN. A failure carries the FQN of the root whose
+ * graph couldn't be resolved plus the same per-root outcome shape.
+ */
+export type MultiActivationResult = {
+    readonly outcome: 'ok';
+    readonly ordered: readonly ParsedSkill[];
+    readonly events: readonly SkillEvent[];
+} | {
+    readonly outcome: 'failed';
+    readonly events: readonly SkillEvent[];
+    readonly failure: {
+        readonly root: ParsedSkill;
+        readonly result: Exclude<ActivationGraphResult, {
+            outcome: 'ok';
+        }>;
+    };
+};
+/**
+ * Resolve the activation graphs for every caller-pinned root and stitch
+ * them into one ordered list (deps before dependents, deduplicated by
+ * FQN). On first-failure-encountered, return early with the failure
+ * payload — the caller throws a `QodoSkillError` so no partial body
+ * lands in the wire payload.
+ *
+ * Events emitted across the resolve are accumulated in `events` so the
+ * caller can forward them to the `SkillsManager` sink. (Failure paths
+ * emit `requires_*` events; the success path emits nothing — the
+ * `activated` events fire when the body is *injected*, which is the
+ * caller's responsibility.)
+ */
+export declare function resolveAllActivations(roots: readonly ParsedSkill[], lookup: SkillLookup): MultiActivationResult;
+/**
+ * Renderer output for the active-skill block. `text` is the block ready
+ * to prepend to the wire `instructions`; `events` records caller-side
+ * telemetry (`activated`, `disable_model_invocation_overridden`,
+ * `allowed_tools_applied` / `_advisory`, `hooks_ignored`) the caller
+ * forwards to `SkillsManager.forwardEvents`.
+ */
+export interface ActiveSkillsRenderResult {
+    readonly text: string;
+    readonly skills: readonly ParsedSkill[];
+    readonly events: readonly SkillEvent[];
+}
+/**
+ * Render the active-skill block from an ordered list of skills (deps
+ * first, dependents next; output of `resolveAllActivations`). Empty input
+ * → empty text + no events.
+ *
+ * Also generates per-skill activation telemetry. The events cover:
+ *
+ *   - `sdk.skill.activated { source: 'caller' }` for every skill.
+ *   - `sdk.skill.disable_model_invocation_overridden` when a caller pin
+ *     forces a `disable-model-invocation: true` skill into the run
+ *     (`skills-activation.md` §2.85).
+ *   - `sdk.skill.allowed_tools_applied` / `_advisory` per the trust gate.
+ *   - `sdk.skill.hooks_ignored` for third-party skills declaring `hooks:`
+ *     (`skills-trust.md` §6).
+ */
+export declare function renderActiveSkillsBlock(ordered: readonly ParsedSkill[], manager: SkillsManager): ActiveSkillsRenderResult;
+/**
+ * Convert a non-ok `ActivationGraphResult` into the human-readable error
+ * message thrown from the caller-pin path. Kept here so the MCP server's
+ * LLM-driven path and the SDK's caller-pin path produce the same wording
+ * on the same failure shape.
+ */
+export declare function activationFailureMessage(root: ParsedSkill, failure: Exclude<ActivationGraphResult, {
+    outcome: 'ok';
+}>): string;
+/**
+ * Cap on the `agent` field carried inside `sdk.skill.fork_declined`
+ * telemetry. The skill-file hard cap is 256 KB; without a per-field
+ * cap on telemetry payloads, a misconfigured (or hostile) skill could
+ * emit multi-KB events that bloat downstream sinks. 128 chars covers
+ * every realistic agent identifier seen in the OSS skill survey;
+ * anything longer gets truncated with an ellipsis marker so the
+ * observability layer sees that overflow happened.
+ */
+export declare const MAX_AGENT_FIELD_CHARS = 128;
+export declare function capAgentField(agent: string): string;
+//# sourceMappingURL=activation.d.ts.map

package/dist/skills/activation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activation.d.ts","sourceRoot":"","sources":["../../src/skills/activation.ts"],"names":[],"mappings":"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"}