@ingram-cloud/sdk 1.4.0 → 1.6.0

package/ts/zod/observability.ts

@@ -24,14 +24,7 @@ import { pageOut } from "./_page.js";
 /** Span kinds emitted by the observability backend. `retrieval` covers vector-store
  *  search (the hosted `file_search` tool, and externally-pushed RAG spans). */
 export const ICSpanKindEnum = z
-	.enum([
-		"run",
-		"model_call",
-		"tool_call",
-		"memory_op",
-		"retrieval",
-		"runtime_event",
-	])
+	.enum(["run", "model_call", "tool_call", "memory_op", "retrieval", "runtime_event"])
 	.meta({ id: "SpanKind" });
 
 /** A single timed unit of work inside a trace. */
@@ -65,7 +58,10 @@ export const SpanNodeOut = SpanOut.extend({
 export const TraceOut = z
 	.object({
 		id: z.string(),
-		smith_id: z.string(),
+		/** Null for a trace no smith owns — an external `/v1/traces:ingest` under a
+		 *  tenant token attributes to none. Such a trace is tenant-scope only: a
+		 *  smith-bound token cannot read it. */
+		smith_id: z.string().nullable(),
 		app_id: z.string().nullable(),
 		run_id: z.string().nullable(),
 		root_kind: ICSpanKindEnum,
@@ -89,25 +85,34 @@ export const TraceDetailOut = TraceOut.extend({
 export const TraceListOut = pageOut(TraceOut, "TraceListOut");
 
 /** Aggregated usage grouped by app, smith, model, or customer. */
+/** The token/cost amounts a usage bucket reports. `tokens` is the grand total
+ *  (input + output); `input_tokens` is the input slice, and `cache_read_tokens`
+ *  / `cache_write_tokens` are sub-slices of input (reads served from the
+ *  provider's prompt cache, writes billed at the cache-write premium). The cache
+ *  hit rate is `cache_read_tokens / input_tokens`. */
+const UsageAmounts = z.object({
+	tokens: z.number(),
+	input_tokens: z.number(),
+	cache_read_tokens: z.number(),
+	cache_write_tokens: z.number(),
+	cost: z.number(),
+	run_count: z.number(),
+});
+
 export const UsageBreakdownOut = z
 	.object({
 		group_by: z.enum(["app", "smith", "model", "customer"]),
-		totals: z.object({
-			tokens: z.number(),
-			cost: z.number(),
-			run_count: z.number(),
-		}),
+		totals: UsageAmounts,
 		groups: z.array(
-			z.object({
-				app: z.string().nullable().optional(),
-				smith: z.string().nullable().optional(),
-				model: z.string().nullable().optional(),
-				// Customer-grouped views label unassigned usage `principal:<smith id>`.
-				customer: z.string().nullable().optional(),
-				tokens: z.number(),
-				cost: z.number(),
-				run_count: z.number(),
-			}),
+			z
+				.object({
+					app: z.string().nullable().optional(),
+					smith: z.string().nullable().optional(),
+					model: z.string().nullable().optional(),
+					// Customer-grouped views label unassigned usage `principal:<smith id>`.
+					customer: z.string().nullable().optional(),
+				})
+				.extend(UsageAmounts.shape),
 		),
 		/** Custom billable events aggregated per meter over the same filters. */
 		meters: z
@@ -146,6 +151,51 @@ export const UsageEventListOut = z
 	})
 	.meta({ id: "UsageEventListOut" });
 
+// ── Span ingestion (POST /v1/traces:ingest) ─────────────────────────────────
+
+/** The request body for span ingestion (externally-pushed spans / OTel).
+ *
+ *  Deliberately permissive: the handler normalizes rather than rejects — an
+ *  unrecognized `kind` degrades to `runtime_event`, missing ids and timestamps
+ *  are generated. Validating {@link ICSpanIn} here would 422 exactly the sloppy
+ *  exporter payloads the endpoint exists to absorb. `ICSpanIn` documents the
+ *  shape for callers; the wire stays open. */
+export const TraceIngestIn = z
+	.object({ spans: z.array(z.record(z.string(), z.unknown())).optional() })
+	.meta({ id: "TraceIngestIn" });
+
+/** The 202 ack for span ingestion: how many spans were written. */
+export const TraceIngestOut = z
+	.object({ accepted: z.number().int() })
+	.meta({ id: "TraceIngestOut" });
+
+/** One span as pushed to `POST /v1/traces:ingest` — the caller-facing contract
+ *  for {@link TraceIngestIn}'s open `spans` array. Every field is optional; the
+ *  tenant is always taken from the token, never the body. A TS type rather than
+ *  a schema precisely because the wire does not enforce it. */
+export interface ICSpanIn {
+	trace_id?: string | null;
+	span_id?: string | null;
+	parent_span_id?: string | null;
+	/** One of {@link ICSpanKindEnum}; anything else lands as `runtime_event`. */
+	kind?: string;
+	name?: string | null;
+	status?: string;
+	started_at?: string | null;
+	ended_at?: string | null;
+	duration_ms?: number | null;
+	model?: string | null;
+	input_tokens?: number | null;
+	output_tokens?: number | null;
+	cache_read_tokens?: number | null;
+	cache_write_tokens?: number | null;
+	attributes?: Record<string, unknown> | null;
+	smith_id?: string | null;
+	app_id?: string | null;
+	run_id?: string | null;
+	open_trace?: boolean;
+}
+
 // ── Inferred consumer-facing types (re-exported by ../responses) ─────────────
 
 export type ICSpanKind = z.infer<typeof ICSpanKindEnum>;

package/ts/zod/projects.ts

@@ -12,6 +12,7 @@
  * `#/components/schemas/<id>` rather than inlining it.
  */
 import { z } from "zod";
+import { pageOut } from "./_page.js";
 
 export const ProjectOut = z
 	.object({
@@ -26,9 +27,7 @@ export const ProjectOut = z
 	})
 	.meta({ id: "ProjectOut" });
 
-export const ProjectListOut = z
-	.object({ data: z.array(ProjectOut) })
-	.meta({ id: "ProjectListOut" });
+export const ProjectListOut = pageOut(ProjectOut, "ProjectListOut");
 
 /**
  * The secret minted when an org mints a project (tenant-admin) token. Shape
@@ -58,7 +57,8 @@ export const ProjectIn = z
 
 export const ProjectTokenIn = z
 	.object({
-		ttl_seconds: z.number().int().nullish(),
+		// Same bounds as `TokenIn.ttl_seconds` — this mints a `tenant:*` token too.
+		ttl_seconds: z.number().int().positive().max(315_360_000).nullish(),
 		name: z.string().nullish(),
 	})
 	.meta({ id: "ProjectTokenIn" });

package/ts/zod/runs.ts

@@ -20,6 +20,7 @@
  * are deliberately not modelled.
  */
 import { z } from "zod";
+import { Actor } from "./_actor.js";
 import { pageOut } from "./_page.js";
 
 /** One message in a run's `input`. `content` is a plain string for a text-only
@@ -29,10 +30,7 @@ import { pageOut } from "./_page.js";
 export const InputMessage = z
 	.object({
 		role: z.string(),
-		content: z.union([
-			z.string(),
-			z.array(z.record(z.string(), z.unknown())),
-		]),
+		content: z.union([z.string(), z.array(z.record(z.string(), z.unknown()))]),
 	})
 	.meta({ id: "InputMessage" });
 
@@ -52,6 +50,17 @@ export const RunUsage = z
 	})
 	.meta({ id: "RunUsage" });
 
+/** One thing that went wrong during a run without ending it — today, a tool source
+ *  the run could not reach. A run that lost its tools still answers, and the answer
+ *  is shaped like a healthy one, so this rides the run's own summary fields rather
+ *  than a nested metadata key nobody reads. */
+export const RunWarning = z
+	.object({
+		code: z.string(),
+		message: z.string(),
+	})
+	.meta({ id: "RunWarning" });
+
 export const RunOut = z
 	.object({
 		id: z.string(),
@@ -78,8 +87,12 @@ export const RunOut = z
 			})
 			.nullable(),
 		stop_reason: z.string().nullable(),
+		// Always present, `[]` on a clean run: absence must never read as "fine".
+		warnings: z.array(RunWarning),
 		usage: RunUsage.nullable(),
 		metadata: z.record(z.string(), z.unknown()).optional(),
+		/** Who started this run. Null on runs created before attribution shipped. */
+		actor: Actor.nullable(),
 		created_at: z.string().nullable(),
 		updated_at: z.string().nullable(),
 	})
@@ -121,6 +134,9 @@ export const Submit = z
 		result: z.record(z.string(), z.unknown()).nullish(),
 		approval_id: z.string().nullish(),
 		decision: z.string().nullish(),
+		/** The answer to an approval's `elicitation`, matching its
+		 *  `requested_schema`; with `decision: "approve"`. */
+		content: z.record(z.string(), z.unknown()).nullish(),
 		actor: z.string().nullish(),
 		reason: z.string().nullish(),
 		stream: z.boolean().optional(),
@@ -131,5 +147,6 @@ export const Submit = z
 
 export type ICInputMessage = z.infer<typeof InputMessage>;
 export type ICRunUsage = z.infer<typeof RunUsage>;
+export type ICRunWarning = z.infer<typeof RunWarning>;
 export type ICRun = z.infer<typeof RunOut>;
 export type ICRunEvent = z.infer<typeof RunEventOut>;

package/ts/zod/schedules.ts

@@ -13,6 +13,7 @@
  * `#/components/schemas/<id>` rather than inlining it.
  */
 import { z } from "zod";
+import { pageOut } from "./_page.js";
 
 /** A schedule's stored input: messages replayed as the run input on each fire. */
 const ScheduleInput = z.array(z.record(z.string(), z.unknown()));
@@ -27,8 +28,6 @@ export const ScheduleOut = z
 		input: ScheduleInput,
 		/** Thread the fired runs append to; null mints a fresh thread per fire. */
 		thread_id: z.string().nullable(),
-		/** Max overlapping fired runs before new fires are skipped. */
-		max_concurrent: z.number().int(),
 		enabled: z.boolean(),
 		next_fire_at: z.string().nullable(),
 		last_fire_at: z.string().nullable(),
@@ -36,9 +35,7 @@ export const ScheduleOut = z
 	})
 	.meta({ id: "ScheduleOut" });
 
-export const ScheduleListOut = z
-	.object({ data: z.array(ScheduleOut) })
-	.meta({ id: "ScheduleListOut" });
+export const ScheduleListOut = pageOut(ScheduleOut, "ScheduleListOut");
 
 /** `POST .../:sid/run_now` — the fire is enqueued onto the smith's serial delivery
  *  lane (not run inline), so the response acknowledges the queued delivery rather
@@ -60,7 +57,6 @@ export const ScheduleIn = z
 		timezone: z.string().default("UTC"),
 		input: ScheduleInput.default([]),
 		thread_id: z.string().nullish(),
-		max_concurrent: z.number().int().default(1),
 		enabled: z.boolean().default(true),
 	})
 	.meta({ id: "ScheduleIn" });
@@ -72,7 +68,6 @@ export const SchedulePatch = z
 		timezone: z.string().nullish(),
 		input: ScheduleInput.nullish(),
 		thread_id: z.string().nullish(),
-		max_concurrent: z.number().int().nullish(),
 		enabled: z.boolean().nullish(),
 	})
 	.meta({ id: "SchedulePatch" });

package/ts/zod/skills.ts

@@ -0,0 +1,85 @@
+/**
+ * Agent Skills (#175) — a folder anchored by SKILL.md, per the Agent Skills
+ * specification, stored as an immutable version and attached to an agent.
+ *
+ * A version's bytes never appear on the wire: `files` lists each path with its
+ * size and content hash, so a tenant can see exactly what they installed.
+ */
+import { z } from "zod";
+
+/** One file in a skill version, as the caller uploaded it. */
+export const SkillFile = z
+	.object({
+		path: z.string(),
+		size: z.number().int(),
+		sha256: z.string(),
+		media_type: z.string(),
+	})
+	.meta({ id: "SkillFile" });
+
+/** One published agent version that froze a reference to this skill version.
+ *  A frozen reference is the only kind that blocks a delete, so this is the
+ *  list a `409 skill_in_use` would name. */
+export const SkillReference = z
+	.object({ agent_id: z.string(), version: z.number().int() })
+	.meta({ id: "SkillReference" });
+
+/** An immutable published version of a skill. */
+export const SkillVersion = z
+	.object({
+		skill_id: z.string(),
+		version: z.number().int(),
+		description: z.string(),
+		license: z.string().nullable(),
+		compatibility: z.unknown().nullable(),
+		metadata: z.record(z.string(), z.unknown()).nullable(),
+		references: z.array(z.string()),
+		scripts: z.array(z.string()),
+		assets: z.array(z.string()),
+		files: z.array(SkillFile),
+		/** Published agent versions holding this one frozen. Always present, `[]`
+		 *  when nothing does. */
+		referenced_by: z.array(SkillReference),
+		bytes: z.number().int(),
+		created_at: z.string(),
+	})
+	.meta({ id: "SkillVersion" });
+
+/** The skill resource. `default_version` is what an agent gets when it names none. */
+export const Skill = z
+	.object({
+		id: z.string(),
+		object: z.literal("skill"),
+		name: z.string(),
+		description: z.string(),
+		default_version: z.number().int(),
+		created_at: z.string(),
+		updated_at: z.string(),
+	})
+	.meta({ id: "Skill" });
+
+export const SkillListOut = z
+	.object({ object: z.literal("list"), data: z.array(Skill) })
+	.meta({ id: "SkillListOut" });
+
+export const SkillVersionListOut = z
+	.object({ object: z.literal("list"), data: z.array(SkillVersion) })
+	.meta({ id: "SkillVersionListOut" });
+
+/** Move the skill's `default_version` to an existing version. */
+export const SkillUpdateIn = z
+	.object({ default_version: z.number().int().positive() })
+	.meta({ id: "SkillUpdateIn" });
+
+/** One skill reference in an agent's `skills` config. Omitted `version` resolves
+ *  to the skill's `default_version` and is frozen at publish. */
+export const SkillRef = z
+	.object({
+		skill_id: z.string(),
+		version: z.number().int().positive().optional(),
+	})
+	.meta({ id: "SkillRef" });
+
+export type ICSkill = z.infer<typeof Skill>;
+export type ICSkillVersion = z.infer<typeof SkillVersion>;
+export type ICSkillReference = z.infer<typeof SkillReference>;

package/ts/zod/smith-revisions.ts

@@ -16,6 +16,7 @@
  * `#/components/schemas/<id>` rather than inlining it.
  */
 import { z } from "zod";
+import { pageOut } from "./_page.js";
 
 /** An immutable snapshot of a smith's effective behaviour config at one revision. */
 export const SmithRevisionOut = z
@@ -38,9 +39,7 @@ export const SmithRevisionOut = z
 	})
 	.meta({ id: "SmithRevisionOut" });
 
-export const RevisionListOut = z
-	.object({ data: z.array(SmithRevisionOut) })
-	.meta({ id: "RevisionListOut" });
+export const RevisionListOut = pageOut(SmithRevisionOut, "RevisionListOut");
 
 // ── Request bodies ──────────────────────────────────────────────────────────
 

package/ts/zod/smiths.ts

@@ -17,6 +17,7 @@
  * `#/components/schemas/<id>` rather than inlining it.
  */
 import { z } from "zod";
+import { SkillRef } from "./skills.js";
 
 // ── Smith response ───────────────────────────────────────────────────────────
 
@@ -40,6 +41,7 @@ export const SmithOut = z
 		vector_store_ids: z.array(z.string()).optional(),
 		/** Registered MCP servers this smith's runs load, by name. Null = all. */
 		mcp_servers: z.array(z.string()).nullish(),
+		skills: z.array(SkillRef).optional(),
 		auto_memory: z.boolean().optional(),
 		memory_consolidation: z.boolean().optional(),
 		/** How the config resolved: by reference, with overrides, or embedded. */
@@ -60,6 +62,7 @@ export const SmithOut = z
 				enabled_hosted_tools: z.array(z.string()),
 				vector_store_ids: z.array(z.string()),
 				mcp_servers: z.array(z.string()).nullable(),
+				skills: z.array(SkillRef),
 				auto_memory: z.boolean().nullable(),
 				memory_consolidation: z.boolean().nullable(),
 			})
@@ -95,6 +98,7 @@ export const SmithCreate = z
 		vector_store_ids: z.array(z.string()).nullish(),
 		/** Scope this smith's runs to these registered MCP servers (by name). */
 		mcp_servers: z.array(z.string()).nullish(),
+		skills: z.array(SkillRef).nullish(),
 		auto_memory: z.boolean().nullish(),
 		memory_consolidation: z.boolean().nullish(),
 	})
@@ -116,6 +120,8 @@ export const SmithPatch = z
 		/** Scope this smith's runs to these registered MCP servers (by name).
 		 *  Null clears the per-smith override (re-inherit the agent's value). */
 		mcp_servers: z.array(z.string()).nullish(),
+		/** Null clears the per-smith override (re-inherit the agent's value). */
+		skills: z.array(SkillRef).nullish(),
 		auto_memory: z.boolean().nullish(),
 		memory_consolidation: z.boolean().nullish(),
 	})

package/ts/zod/tenant.ts

@@ -12,6 +12,7 @@
  * `#/components/schemas/<id>` rather than inlining it.
  */
 import { z } from "zod";
+import { Actor } from "./_actor.js";
 import { pageOut } from "./_page.js";
 
 // ── Events (poll mirror of the webhook firehose) ─────────────────────────────
@@ -26,6 +27,8 @@ export const EventOut = z
 		type: z.string(),
 		smith_id: z.string().nullable(),
 		data: z.record(z.string(), z.unknown()),
+		/** Who acted. Null on events recorded before attribution shipped. */
+		actor: Actor.nullable(),
 		created_at: z.string().nullable(),
 	})
 	.meta({ id: "EventOut" });
@@ -58,9 +61,7 @@ export const WebhookCreateOut = z
 	.meta({ id: "WebhookCreateOut" });
 
 /** The patch/delete-adjacent ack shape (just the id). */
-export const WebhookIdOut = z
-	.object({ id: z.string() })
-	.meta({ id: "WebhookIdOut" });
+export const WebhookIdOut = z.object({ id: z.string() }).meta({ id: "WebhookIdOut" });
 
 export const WebhookIn = z
 	.object({
@@ -115,7 +116,10 @@ export const WebhookDeliveryOut = z
 	})
 	.meta({ id: "WebhookDeliveryOut" });
 
-export const WebhookDeliveryListOut = pageOut(WebhookDeliveryOut, "WebhookDeliveryListOut");
+export const WebhookDeliveryListOut = pageOut(
+	WebhookDeliveryOut,
+	"WebhookDeliveryListOut",
+);
 
 /** The redeliver ack — the outcome of the forced re-attempt. */
 export const WebhookRedeliverOut = z
@@ -162,7 +166,9 @@ export const TokenIn = z
 		scope: z.string().default("smith"),
 		smith_id: z.string().nullish(),
 		permissions: z.array(z.string()).nullish(),
-		ttl_seconds: z.number().int().nullish(),
+		// Positive and bounded: `0` used to read as "no expiry" and mint a permanent
+		// admin token, and a ttl past year 275760 overflows the `Date` we serialize.
+		ttl_seconds: z.number().int().positive().max(315_360_000).nullish(),
 		name: z.string().nullish(),
 	})
 	.meta({ id: "TokenIn" });
@@ -346,3 +352,25 @@ export type ICModelCatalog = z.infer<typeof ModelsListOut>;
 export type ICModelKey = z.infer<typeof ModelKeyOut>;
 export type ICProvider = z.infer<typeof ProviderOut>;
 export type ICAuthorizeRequest = z.infer<typeof AuthorizeRequestOut>;
+
+// ── Sandbox secrets (env a tenant's sandboxes carry) ─────────────────────────
+
+/** One secret by name. The value is NEVER echoed — only that it is set. */
+export const SandboxSecretOut = z
+	.object({
+		name: z.string(),
+		updated_at: z.string().nullable(),
+	})
+	.meta({ id: "SandboxSecretOut" });
+
+export const SandboxSecretListOut = z
+	.object({ data: z.array(SandboxSecretOut) })
+	.meta({ id: "SandboxSecretListOut" });
+
+export const SandboxSecretIn = z
+	.object({ value: z.string() })
+	.meta({ id: "SandboxSecretIn" });
+
+export const SandboxSecretConfiguredOut = z
+	.object({ name: z.string(), configured: z.boolean() })
+	.meta({ id: "SandboxSecretConfiguredOut" });

package/ts/zod/vector-stores.ts

@@ -16,6 +16,7 @@
  * rather than being accepted and ignored.
  */
 import { z } from "zod";
+import { oaiListOut } from "./_page.js";
 
 // ── Chunking ─────────────────────────────────────────────────────────────────
 
@@ -53,7 +54,9 @@ export const ChunkingStrategyOut = z
 /** File attributes: ≤16 keys, key ≤64 chars, value string(≤512)|number|bool. */
 export const VectorStoreAttributes = z
 	.record(z.string().max(64), z.union([z.string().max(512), z.number(), z.boolean()]))
-	.refine((v) => Object.keys(v).length <= 16, { message: "at most 16 attribute keys" });
+	.refine((v) => Object.keys(v).length <= 16, {
+		message: "at most 16 attribute keys",
+	});
 
 /** A filter node: a comparison (`type` eq/ne/gt/gte/lt/lte/in/nin over `key`/
  *  `value`) or a compound (`type` and/or over nested `filters`). The grammar is
@@ -138,15 +141,7 @@ export const VectorStoreOut = z
 	.meta({ id: "VectorStoreOut" });
 
 /** Vector stores, in OpenAI's `list` envelope. */
-export const VectorStoreListOut = z
-	.object({
-		object: z.literal("list"),
-		data: z.array(VectorStoreOut),
-		first_id: z.string().nullable(),
-		last_id: z.string().nullable(),
-		has_more: z.boolean(),
-	})
-	.meta({ id: "VectorStoreListOut" });
+export const VectorStoreListOut = oaiListOut(VectorStoreOut, "VectorStoreListOut");
 
 /** Modify body (OpenAI uses `POST`, not `PATCH`). */
 export const VectorStorePatch = z
@@ -200,15 +195,10 @@ export const VectorStoreFileOut = z
 	})
 	.meta({ id: "VectorStoreFileOut" });
 
-export const VectorStoreFileListOut = z
-	.object({
-		object: z.literal("list"),
-		data: z.array(VectorStoreFileOut),
-		first_id: z.string().nullable(),
-		last_id: z.string().nullable(),
-		has_more: z.boolean(),
-	})
-	.meta({ id: "VectorStoreFileListOut" });
+export const VectorStoreFileListOut = oaiListOut(
+	VectorStoreFileOut,
+	"VectorStoreFileListOut",
+);
 
 /** Update body: attributes only (chunking is frozen once indexed). */
 export const VectorStoreFileUpdate = z