@agent-os-sdk/client 0.9.14 → 0.9.15

package/src/index.ts

@@ -17,7 +17,7 @@
  * import { createClient } from "@agent-os-sdk/client";
  * 
  * const api = createClient({ baseUrl, headers });
- * const { data } = await api.POST("/v1/api/graph/commit", { body: {...} });
+ * const { data } = await api.POST("/v1/api/contracts/validate", { body: {...} });
  * ```
  * 
  * @example Custom Client (ergonomic wrapper)
@@ -25,7 +25,7 @@
  * import { AgentOsClient } from "@agent-os-sdk/client";
  * 
  * const client = new AgentOsClient({ baseUrl, auth: {...} });
- * const { data } = await client.graphs.commit({...});
+ * const { data } = await client.contracts.validate({...});
  * ```
  */
 
@@ -97,15 +97,35 @@ export type { SSEEvent, SSEOptions } from "./sse/client.js";
 export * from "./modules/agents.js";
 export * from "./modules/auth.js";
 export * from "./modules/chatwoot.js";
+export * from "./modules/catalog.js";
+export * from "./modules/contracts.js";
 export * from "./modules/credentials.js";
 export * from "./modules/datasets.js";
+export {
+    EvaluationModule,
+    type EvalDataset,
+    type DatasetListResponse,
+    type Experiment,
+    type ExperimentResults,
+    type ExperimentListResponse,
+    type DatasetExample as EvaluationDatasetExample,
+    type ExamplesListResponse,
+    type ExampleData,
+    type KpiAggregate,
+    type KpiAggregateListResponse,
+    type KpiAlert,
+    type KpiAlertListResponse
+} from "./modules/evaluation.js";
+export * from "./modules/improvements.js";
 export * from "./modules/me.js";
 export * from "./modules/members.js";
+export * from "./modules/metaAgent.js";
 export * from "./modules/observability.js";
 export * from "./modules/presets.js";
 export * from "./modules/prompts.js";
 export * from "./modules/roles.js";
 export * from "./modules/runs.js";
+export * from "./modules/templates.js";
 export * from "./modules/triggers.js";
 export * from "./modules/usage.js";
 export * from "./modules/workspaces.js";

package/src/modules/agents.ts

@@ -53,6 +53,22 @@ export interface GraphValidationResponse {
     warnings?: string[];
 }
 
+export interface AgentDraftIrResponse {
+    id: string;
+    name: string;
+    draft_ir_revision?: string | null;
+    draftIrRevision?: string | null;
+    draft_updated_at?: string | null;
+    draftUpdatedAt?: string | null;
+    live_bundle_id?: string | null;
+    liveBundleId?: string | null;
+    etag?: string;
+    e_tag?: string;
+    eTag?: string;
+    ir_json?: Record<string, unknown> | null;
+    irJson?: Record<string, unknown> | null;
+}
+
 export interface UpsertAgentCredentialBindingRequest {
     credential_id: string;
     alias: string;
@@ -274,24 +290,64 @@ export class AgentsModule {
         });
     }
 
+    // ======================== Draft IR ========================
+
+    async getDraftIr(agentId: string): Promise<APIResponse<AgentDraftIrResponse>> {
+        return this.client.GET<AgentDraftIrResponse>("/v1/api/agents/{id}/draft/ir", {
+            params: { path: { id: agentId } },
+            headers: this.headers(),
+        });
+    }
+
+    async updateDraftIr(
+        agentId: string,
+        irJson: Record<string, unknown>,
+        options?: { if_match?: string }
+    ): Promise<APIResponse<AgentDraftIrResponse>> {
+        const headers: Record<string, string> = { ...this.headers() };
+        if (options?.if_match) {
+            headers["If-Match"] = options.if_match;
+        }
+
+        const response = await this.client.PUT<AgentDraftIrResponse | { data?: AgentDraftIrResponse }>("/v1/api/agents/{id}/draft/ir", {
+            params: { path: { id: agentId } },
+            body: {
+                ir_json: irJson,
+            } as any,
+            headers,
+        });
+
+        const unwrapped =
+            response.data &&
+                typeof response.data === "object" &&
+                "data" in response.data &&
+                typeof (response.data as { data?: unknown }).data === "object"
+                ? ((response.data as { data?: AgentDraftIrResponse }).data ?? undefined)
+                : (response.data as AgentDraftIrResponse | undefined);
+
+        return {
+            ...response,
+            data: unwrapped,
+        };
+    }
+
     // ======================== Publishing ========================
 
     /**
-     * Publish a new version (bundle) of the agent.
+     * Publish the committed agent artifact pointed to by the current authoring revision.
+     * The client does not send authoring JSON anymore.
      * @param agentId The agent UUID
-     * @param graph_spec The graph specification to publish
      * @param options Optional settings: version_label for tagging, set_as_live to make this the active version, idempotency_key for safe retries
      * @returns Bundle response with version details
      * @example
      * ```ts
-     * const { data: bundle } = await client.agents.publish(agentId, graphSpec, {
+     * const { data: bundle } = await client.agents.publish(agentId, {
      *   idempotency_key: "publish-unique-key"
      * });
      * ```
      */
     async publish(
         agentId: string,
-        graph_spec: Record<string, unknown>,
         options?: {
             version_label?: string | null;
             set_as_live?: boolean;
@@ -308,7 +364,6 @@ export class AgentsModule {
         return this.client.POST<components["schemas"]["BundleResponse"]>("/v1/api/agents/{id}/publish", {
             params: { path: { id: agentId } },
             body: {
-                graph_spec,
                 version_label: options?.version_label ?? null,
                 set_as_live: options?.set_as_live ?? true,
                 required_tools: options?.required_tools ?? []
@@ -321,11 +376,11 @@ export class AgentsModule {
 
     /**
      * Get the manifest for a specific bundle.
-     * Returns artifact metadata and graph_spec.
+     * Returns artifact metadata only.
      * @example
      * ```ts
      * const { data } = await client.agents.getBundleManifest(agentId, bundleId);
-     * console.log(data?.graph_spec);
+     * console.log(data?.artifact_hash);
      * ```
      */
     async getBundleManifest(agentId: string, bundleId: string): Promise<APIResponse<BundleManifestResponse>> {
@@ -376,7 +431,6 @@ export interface BundleManifestResponse {
     format?: string;
     schema_version?: string;
     created_at?: string;
-    graph_spec?: Record<string, unknown>;
 }
 
 export interface BundleMermaidResponse {

package/src/modules/contracts.ts

@@ -0,0 +1,80 @@
+import type { APIResponse, RawClient } from "../client/raw.js";
+
+export interface ContractsValidationIssue {
+    code: string;
+    message: string;
+    path?: string;
+    severity?: string;
+}
+
+export type ContractsErrorCode =
+    | "CONTRACT_ID_INVALID"
+    | "RUNTIME_PACKAGE_COMPILE_INVALID"
+    | "INTERNAL_UNAUTHORIZED"
+    | "KERNEL_UNAVAILABLE"
+    | "KERNEL_ERROR"
+    | "INTERNAL_ERROR"
+    | "VALIDATION_ERROR";
+
+export interface ContractsErrorResponse {
+    code: ContractsErrorCode;
+    message: string;
+    errors?: ContractsValidationIssue[];
+    supported_contract_ids?: string[];
+}
+
+export interface ContractsSupportedResponse {
+    contract_ids: string[];
+}
+
+export interface ContractsValidateRequest {
+    contract_id: string;
+    spec: unknown;
+}
+
+export interface ContractsValidateResponse {
+    contract_id: string;
+    valid: boolean;
+    errors: ContractsValidationIssue[];
+    warnings: ContractsValidationIssue[];
+}
+
+export interface ContractsCompileRuntimePackageRequest {
+    ir_spec: unknown;
+    capability_registry_spec: unknown;
+    policy_refs?: Record<string, unknown>;
+    runtime_config_refs?: Record<string, unknown>;
+    package_id?: string;
+    metadata?: Record<string, unknown>;
+    compiled_at?: string;
+}
+
+export interface ContractsCompileRuntimePackageResponse {
+    package_spec: Record<string, unknown>;
+}
+
+export class ContractsModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) {}
+
+    async supported(): Promise<APIResponse<ContractsSupportedResponse>> {
+        return this.client.GET<ContractsSupportedResponse>("/v1/api/contracts/supported", {
+            headers: this.headers(),
+        });
+    }
+
+    async validate(body: ContractsValidateRequest): Promise<APIResponse<ContractsValidateResponse>> {
+        return this.client.POST<ContractsValidateResponse>("/v1/api/contracts/validate", {
+            body,
+            headers: this.headers(),
+        });
+    }
+
+    async compileRuntimePackage(
+        body: ContractsCompileRuntimePackageRequest,
+    ): Promise<APIResponse<ContractsCompileRuntimePackageResponse>> {
+        return this.client.POST<ContractsCompileRuntimePackageResponse>("/v1/api/contracts/compile/runtime-package", {
+            body,
+            headers: this.headers(),
+        });
+    }
+}

package/src/modules/evaluation.ts

@@ -63,6 +63,52 @@ export interface ExamplesListResponse {
     total: number;
 }
 
+export interface KpiAggregate {
+    kpi_key: string;
+    kpi_binding_version: string;
+    source_scope: string;
+    unit?: string | null;
+    events_n: number;
+    runs_n: number;
+    threads_n: number;
+    outcome_linked_n: number;
+    numeric_values_n: number;
+    value_number_sum?: number | null;
+    value_number_avg?: number | null;
+    value_number_min?: number | null;
+    value_number_max?: number | null;
+    first_recorded_at: string;
+    last_recorded_at: string;
+}
+
+export interface KpiAggregateListResponse {
+    items: KpiAggregate[];
+    total: number;
+    skip: number;
+    take: number;
+}
+
+export interface KpiAlert {
+    alert_code: string;
+    severity: "critical" | "warning" | "info";
+    kpi_key: string;
+    kpi_binding_version?: string | null;
+    source_scope?: string | null;
+    message: string;
+    events_n: number;
+    numeric_values_n: number;
+    outcome_linked_n: number;
+    first_recorded_at?: string | null;
+    last_recorded_at?: string | null;
+}
+
+export interface KpiAlertListResponse {
+    items: KpiAlert[];
+    total: number;
+    skip: number;
+    take: number;
+}
+
 export class EvaluationModule {
     constructor(private client: RawClient, private headers: () => Record<string, string>) { }
 
@@ -186,4 +232,38 @@ export class EvaluationModule {
             headers: this.headers(),
         });
     }
+
+    async listKpiAggregates(params?: {
+        runId?: string;
+        threadId?: string;
+        kpiKey?: string;
+        kpiBindingVersion?: string;
+        sourceScope?: string;
+        recordedAfter?: string;
+        recordedBefore?: string;
+        skip?: number;
+        take?: number;
+    }): Promise<APIResponse<KpiAggregateListResponse>> {
+        return this.client.GET<KpiAggregateListResponse>("/v1/api/evaluations/kpi-results/aggregates", {
+            params: { query: params },
+            headers: this.headers(),
+        });
+    }
+
+    async listKpiAlerts(params?: {
+        runId?: string;
+        threadId?: string;
+        kpiKey?: string;
+        sourceScope?: string;
+        recordedAfter?: string;
+        recordedBefore?: string;
+        staleAfterHours?: number;
+        skip?: number;
+        take?: number;
+    }): Promise<APIResponse<KpiAlertListResponse>> {
+        return this.client.GET<KpiAlertListResponse>("/v1/api/evaluations/kpi-results/alerts", {
+            params: { query: params },
+            headers: this.headers(),
+        });
+    }
 }

package/src/modules/improvements.ts

@@ -0,0 +1,71 @@
+import type { APIResponse, RawClient } from "../client/raw.js";
+
+export interface ImprovementCase {
+    id: string;
+    tenant_id: string;
+    workspace_id: string;
+    agent_id: string;
+    champion_bundle_id: string;
+    challenger_bundle_id: string;
+    eval_experiment_id?: string | null;
+    status: string;
+    trigger_kind: string;
+    improvement_policy_ref?: string | null;
+    summary?: string | null;
+    decision_comparison_id?: string | null;
+    approval_decision_reason?: string | null;
+    promotion_decision_reason?: string | null;
+    rejection_reason?: string | null;
+    rollback_reason?: string | null;
+    rollback_decision_comparison_id?: string | null;
+    rollback_source_bundle_id?: string | null;
+    rollback_target_bundle_id?: string | null;
+    created_by?: string | null;
+    approved_by?: string | null;
+    promoted_by?: string | null;
+    rejected_by?: string | null;
+    rolled_back_by?: string | null;
+    created_at: string;
+    updated_at: string;
+    approved_at?: string | null;
+    promoted_at?: string | null;
+    rejected_at?: string | null;
+    rolled_back_at?: string | null;
+}
+
+export interface ImprovementCaseListResponse {
+    items: ImprovementCase[];
+    total: number;
+    skip: number;
+    take: number;
+}
+
+export class ImprovementsModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) {}
+
+    async list(params?: {
+        agentId?: string;
+        status?: string;
+        skip?: number;
+        take?: number;
+    }): Promise<APIResponse<ImprovementCaseListResponse>> {
+        return this.client.GET<ImprovementCaseListResponse>("/v1/api/improvements/cases", {
+            params: {
+                query: {
+                    agentId: params?.agentId,
+                    status: params?.status,
+                    skip: params?.skip,
+                    take: params?.take,
+                },
+            },
+            headers: this.headers(),
+        });
+    }
+
+    async get(caseId: string): Promise<APIResponse<ImprovementCase>> {
+        return this.client.GET<ImprovementCase>("/v1/api/improvements/cases/{caseId}", {
+            params: { path: { caseId } },
+            headers: this.headers(),
+        });
+    }
+}

package/src/modules/metaAgent.ts

@@ -0,0 +1,87 @@
+import type { APIResponse, RawClient } from "../client/raw.js";
+
+export interface MetaAgentPatchValidationIssue {
+    code: string;
+    message: string;
+    node_id?: string | null;
+    path?: string | null;
+}
+
+export interface MetaAgentPreviewValidationIssue {
+    code: string;
+    message: string;
+    path?: string | null;
+    severity?: string | null;
+}
+
+export interface MetaAgentPatchOp {
+    op: string;
+    node_id?: string | null;
+    kind?: string | null;
+    label?: string | null;
+    data?: Record<string, unknown> | null;
+    set?: Record<string, unknown> | null;
+    from?: string | null;
+    to?: string | null;
+    entrypoint?: string | null;
+}
+
+export interface MetaAgentPatchProposal {
+    patch_id: string;
+    description?: string | null;
+    ops: MetaAgentPatchOp[];
+}
+
+export interface MetaAgentPatchProposalResponse {
+    agent_id: string;
+    draft_revision?: string | null;
+    draft_etag: string;
+    source_contract: "agent_ir.v1";
+    patch?: MetaAgentPatchProposal | null;
+    preview_draft_ir?: Record<string, unknown> | null;
+    preview_valid: boolean;
+    preview_errors: MetaAgentPreviewValidationIssue[];
+    preview_warnings: MetaAgentPreviewValidationIssue[];
+    valid: boolean;
+    errors: MetaAgentPatchValidationIssue[];
+    message: string;
+}
+
+export interface MetaAgentApplyPatchResponse {
+    agent_id: string;
+    draft_revision?: string | null;
+    draft_etag_before: string;
+    draft_etag_after: string;
+    patch_id: string;
+    source_contract: "agent_ir.v1";
+    applied_at: string;
+    applied_by?: string | null;
+    draft_ir: Record<string, unknown>;
+}
+
+export class MetaAgentModule {
+    constructor(private client: RawClient, private headers: () => Record<string, string>) {}
+
+    async propose(agentId: string, instruction: string): Promise<APIResponse<MetaAgentPatchProposalResponse>> {
+        return this.client.POST<MetaAgentPatchProposalResponse>("/v1/api/agents/{id}/meta-agent/proposals", {
+            params: { path: { id: agentId } },
+            headers: this.headers(),
+            body: { instruction },
+        });
+    }
+
+    async apply(
+        agentId: string,
+        draftEtag: string,
+        patch: MetaAgentPatchProposal,
+    ): Promise<APIResponse<MetaAgentApplyPatchResponse>> {
+        return this.client.POST<MetaAgentApplyPatchResponse>("/v1/api/agents/{id}/meta-agent/proposals/apply", {
+            params: { path: { id: agentId } },
+            headers: this.headers(),
+            body: {
+                draft_etag: draftEtag,
+                patch,
+            },
+        });
+    }
+}

package/src/modules/presets.ts

@@ -32,56 +32,111 @@ const TRIGGER_TYPE_MAP: Record<string, { type: string; template_slug: string }>
   schedule: { type: "schedule", template_slug: "cron" },
 };
 
-const OUTPUT_NODE_MAP: Record<string, { kind: string; config: Record<string, unknown> }> = {
-  chatwoot: { kind: "output.chatwoot", config: {} },
-  http: { kind: "output.http", config: {} },
-};
+function buildAgentDefinitionId(name: string): string {
+  const normalized = name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, ".")
+    .replace(/\.{2,}/g, ".")
+    .replace(/^\.|\.$/g, "");
+  return `agent.${normalized || "untitled"}`;
+}
 
-function generateGraphSpec(config: AgentTemplateConfig): Record<string, unknown> {
-  const triggerMapping = TRIGGER_TYPE_MAP[config.trigger_type] ?? TRIGGER_TYPE_MAP.webhook;
-  const outputMapping = OUTPUT_NODE_MAP[config.output_type] ?? OUTPUT_NODE_MAP.http;
-
-  // Safe validation (TS knows these keys exist in the constant, but runtime check is good practice)
-  if (!triggerMapping) throw new Error(`Invalid trigger type: ${config.trigger_type}`);
-  if (!outputMapping) throw new Error(`Invalid output type: ${config.output_type}`);
-
-  const nodes = [
-    {
-      id: "node-llm",
-      kind: "llm.chat",
-      label: "LLM",
-      config: {
-        model: config.llm?.model || "gpt-4o",
-        system_prompt: config.llm?.system_prompt || "You are a helpful assistant.",
-        ...(config.llm?.credential_id ? { credential_id: config.llm.credential_id } : {}),
+function generateAgentIr(config: AgentTemplateConfig): Record<string, unknown> {
+  const agentDefinitionId = buildAgentDefinitionId(config.name);
+  const triggerLabel = config.trigger_type === "schedule" ? "Scheduled Trigger" : "Incoming Trigger";
+  const outputLabel = config.output_type === "chatwoot" ? "Chatwoot Output" : "HTTP Output";
+
+  return {
+    ir_version: "1.0",
+    agent_definition_id: agentDefinitionId,
+    version: "1.0.0",
+    metadata: {
+      name: config.name,
+      description: "Preset-generated agent_ir.v1 draft",
+    },
+    state_schema: {
+      type: "object",
+      properties: {
+        global: {
+          type: "object",
+        },
       },
-      ui: { x: 300, y: 200 },
     },
-    {
-      id: "node-output",
-      ...outputMapping,
-      label: "Output",
-      ui: { x: 500, y: 200 },
+    inputs_schema: {
+      type: "object",
+      properties: {
+        message: {
+          type: "string",
+        },
+      },
+      required: ["message"],
     },
-  ];
-
-  const edges = [
-    { from: "node-llm", to: "node-output" },
-  ];
-
-  const triggers = [
-    {
-      type: `${triggerMapping.template_slug}.${triggerMapping.type}`,
-      config: { events: ["message_created"] },
+    outputs_schema: {
+      type: "object",
     },
-  ];
-
-  return {
-    version: "1",
-    entrypoint: "node-llm",
-    nodes,
-    edges,
-    triggers,
+    outcome_schema: {
+      type: "object",
+      properties: {
+        preset_ready: {
+          type: "boolean",
+        },
+      },
+      required: ["preset_ready"],
+    },
+    kpi_bindings: [
+      {
+        kpi_ref: `${agentDefinitionId}.preset_ready`,
+        source_scope: "outcome",
+        source_path: "preset_ready",
+      },
+    ],
+    evaluation_policy: {
+      execution_mode: "async",
+      evaluators: [
+        {
+          evaluator_ref: `eval.${agentDefinitionId}.preset_shape_v1`,
+          kind: "rule",
+        },
+      ],
+      sampling_policy: {
+        mode: "all",
+      },
+    },
+    improvement_policy_ref: null,
+    nodes: [
+      {
+        id: "start",
+        kind: "start",
+        label: triggerLabel,
+        config: {},
+        bindings: {},
+        editability: { mode: "read_only" },
+      },
+      {
+        id: "draft_output",
+        kind: "end",
+        label: outputLabel,
+        config: {},
+        bindings: {},
+        editability: { mode: "full" },
+      },
+    ],
+    edges: [
+      {
+        id: "edge_start_to_output",
+        from: "start",
+        to: "draft_output",
+        kind: "default",
+        priority: 0,
+      },
+    ],
+    capability_registry_refs: [],
+    policies: {},
+    editability: {
+      mode: "full",
+    },
+    entrypoints: ["start"],
   };
 }
 
@@ -129,14 +184,27 @@ export class PresetsModule {
         return null;
       }
 
-      const graphSpec = generateGraphSpec(config);
-
-      const { data: bundle, error: publishError } = await this._agents.publish(
+      const { error: draftError } = await this._agents.updateDraftIr(
         agent.id,
-        graphSpec,
-        { set_as_live: true, idempotency_key: generateUUID() }
+        generateAgentIr(config),
+        { if_match: `"${agent.id}:0"` },
       );
 
+      if (draftError) {
+        console.error("[AgentOS SDK] Failed to save agent_ir.v1 draft:", draftError);
+        return {
+          agent_id: agent.id,
+          agent_name: agent.name,
+          status: "draft",
+        };
+      }
+
+      const { data: bundle, error: publishError } = await this._agents.publish(agent.id, {
+        set_as_live: true,
+        required_tools: [],
+        idempotency_key: generateUUID(),
+      });
+
       if (publishError) {
         console.error("[AgentOS SDK] Failed to publish bundle:", publishError);
         return {