@re-cinq/agent-contracts 0.12.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @re-cinq/agent-contracts
2
2
 
3
- TypeScript types and a thin, typed client for the [ai-agent-subsystem](https://github.com/re-cinq/ai-agent-subsystem) Custom Resources: **Agent**, **Station**, and **AgentDefinition** (API group `agents.re-cinq.com/v1alpha1`).
3
+ TypeScript types and a thin, typed client for the [ai-agent-subsystem](https://github.com/re-cinq/ai-agent-subsystem) Custom Resources: **Agent**, **Station**, **AgentDefinition** and **ModelCatalog** (API group `agents.re-cinq.com/v1alpha1`).
4
4
 
5
5
  The types are generated directly from the D source structs that define the CRDs, so they cannot drift from the controller. A CI drift check fails the build if the committed output stops matching the model.
6
6
 
@@ -12,9 +12,9 @@ npm install @re-cinq/agent-contracts
12
12
 
13
13
  ## What you get
14
14
 
15
- - **Types** for every resource and nested field: `Agent`, `Station`, `AgentDefinition`, their `*Spec`/`*Status` shapes, and the string-literal unions (`Phase`, `ConcurrencyPolicy`, `PermissionMode`, ...).
15
+ - **Types** for every resource and nested field: `Agent`, `Station`, `AgentDefinition`, their `*Spec`/`*Status` shapes, the `ModelCatalog`, `ModelCatalogStatus`, `VendorModels` and `ModelInfo` types, and the string-literal unions (`Phase`, `ConcurrencyPolicy`, `PermissionMode`, ...).
16
16
  - **Constants**: `GROUP`, `VERSION`, `DEFAULT_NAMESPACE`.
17
- - **`AgentContractsClient`** — create/read/list Agents and server-side-apply Stations and AgentDefinitions.
17
+ - **`AgentContractsClient`** — create/read/list Agents, server-side-apply Stations and AgentDefinitions, and read the ModelCatalog.
18
18
  - **Helpers**: `isTerminal(agent)` and `waitForAgent(client, name, options?)`.
19
19
 
20
20
  The client takes a `KubeTransport` you supply, so its logic stays decoupled from any particular HTTP stack and is deterministically testable with an in-memory fake — no cluster, no mocks.
@@ -90,6 +90,7 @@ console.log(finished.status?.phase, finished.status?.prUrl);
90
90
  | `createAgent(agent)` | Create one Agent run. |
91
91
  | `getAgent(name)` | Read one Agent by name. |
92
92
  | `findAgents(labelSelector)` | List Agents matching a Kubernetes label selector. |
93
+ | `getModelCatalog()` | Read the `default` ModelCatalog in the client's namespace: the models the subsystem can run. Throws on a 404 when the controller runs without the model-catalog component. |
93
94
  | `applyStation(station)` | Server-side apply a Station. |
94
95
  | `applyAgentDefinition(def)` | Server-side apply an AgentDefinition. |
95
96
  | `isTerminal(agent)` | `true` once `status.phase` is `Succeeded` or `Failed`. |
package/dist/client.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import type { Agent, AgentDefinition, Station } from "./types.generated.js";
1
+ import type { Agent, AgentDefinition, ModelCatalog, Station } from "./types.generated.js";
2
2
  export declare const GROUP = "agents.re-cinq.com";
3
3
  export declare const VERSION = "v1alpha1";
4
4
  export declare const DEFAULT_NAMESPACE = "ai-agents";
@@ -29,6 +29,8 @@ export declare class AgentContractsClient {
29
29
  getAgent(name: string): Promise<Agent>;
30
30
  /** List Agents matching a Kubernetes label selector. */
31
31
  findAgents(labelSelector: string): Promise<Agent[]>;
32
+ /** Read the models the subsystem can run (the controller's `default` ModelCatalog). */
33
+ getModelCatalog(): Promise<ModelCatalog>;
32
34
  /** Server-side apply an AgentDefinition (the UI uses this to push edited YAML). */
33
35
  applyAgentDefinition(def: AgentDefinition): Promise<AgentDefinition>;
34
36
  /** Server-side apply a Station. */
package/dist/client.js CHANGED
@@ -7,6 +7,7 @@ export const GROUP = "agents.re-cinq.com";
7
7
  export const VERSION = "v1alpha1";
8
8
  export const DEFAULT_NAMESPACE = "ai-agents";
9
9
  const FIELD_MANAGER = "agent-contracts";
10
+ const MODEL_CATALOG_NAME = "default";
10
11
  const TERMINAL_PHASES = ["Succeeded", "Failed"];
11
12
  /** True once an Agent run has reached a terminal phase (Succeeded / Failed). */
12
13
  export function isTerminal(agent) {
@@ -51,6 +52,14 @@ export class AgentContractsClient {
51
52
  const list = enforceHTTPSuccess(res);
52
53
  return list.items ?? [];
53
54
  }
55
+ /** Read the models the subsystem can run (the controller's `default` ModelCatalog). */
56
+ async getModelCatalog() {
57
+ const res = await this.transport.request({
58
+ method: "GET",
59
+ path: `${namespacedPath("modelcatalogs", this.namespace)}/${MODEL_CATALOG_NAME}`,
60
+ });
61
+ return enforceHTTPSuccess(res);
62
+ }
54
63
  /** Server-side apply an AgentDefinition (the UI uses this to push edited YAML). */
55
64
  applyAgentDefinition(def) {
56
65
  return this.apply("agentdefinitions", def);
@@ -5,6 +5,8 @@ export type SelectEvent = "tool_call" | "message" | "tool_result" | "result" | "
5
5
  export type SelectRole = "assistant" | "user";
6
6
  export type SinkType = "stdout" | "http" | "file";
7
7
  export type ConcurrencyPolicy = "Allow" | "Forbid" | "Replace";
8
+ export type Execution = "interactive" | "batch" | "realtime";
9
+ export type BatchTimeoutAction = "fail" | "fallback";
8
10
  export type Phase = "Pending" | "Running" | "Succeeded" | "Failed";
9
11
  export interface ObjectMeta {
10
12
  name?: string;
@@ -15,6 +17,8 @@ export interface ObjectMeta {
15
17
  creationTimestamp?: string;
16
18
  labels?: Record<string, string>;
17
19
  annotations?: Record<string, string>;
20
+ finalizers?: string[];
21
+ deletionTimestamp?: string;
18
22
  }
19
23
  export interface EnvVar {
20
24
  name: string;
@@ -26,13 +30,24 @@ export interface SecretRef {
26
30
  /** Allowlisted secret-store key. */
27
31
  ref: string;
28
32
  }
33
+ export interface McpHeader {
34
+ /** HTTP header name, e.g. X-API-Key. */
35
+ name: string;
36
+ /** Allowlisted secret-store key holding the header value. */
37
+ ref: string;
38
+ }
29
39
  export interface McpServer {
30
40
  name: string;
31
41
  transport: McpTransport;
32
42
  command?: string;
33
43
  args?: string[];
34
44
  url?: string;
45
+ /** Deprecated: use headers. Allowlisted secret-store key sent as the Authorization header. */
35
46
  headers_secret?: string;
47
+ /** http/sse: headers whose values come from the secret store. */
48
+ headers?: McpHeader[];
49
+ /** stdio: environment variables for the server process whose values come from the secret store. */
50
+ env?: SecretRef[];
36
51
  }
37
52
  export interface RepoRef {
38
53
  name: string;
@@ -94,6 +109,18 @@ export interface OutputSpec {
94
109
  sinks?: OutputSink[];
95
110
  watch?: OutputWatch[];
96
111
  }
112
+ export interface BatchSpec {
113
+ /** Minutes to wait for the batch result before onTimeout applies. */
114
+ timeoutMinutes?: number;
115
+ /** fail marks the Agent Failed; fallback reruns the work as a CLI Job. */
116
+ onTimeout?: BatchTimeoutAction;
117
+ /** Output token ceiling (max_tokens) for the batch request. */
118
+ maxTokens?: number;
119
+ }
120
+ export interface RealtimeSpec {
121
+ /** Minutes without a prompt or a running turn after which the session ends and its conversation is saved. */
122
+ idleTimeoutMinutes?: number;
123
+ }
97
124
  /** The reusable recipe for a coding agent task. */
98
125
  export interface AgentDefinitionSpec {
99
126
  /** Human summary for operators. */
@@ -106,6 +133,9 @@ export interface AgentDefinitionSpec {
106
133
  disallowed_tools?: string[];
107
134
  permission_mode?: PermissionMode;
108
135
  max_turns?: number;
136
+ execution?: Execution;
137
+ batch?: BatchSpec;
138
+ realtime?: RealtimeSpec;
109
139
  resources?: AgentResources;
110
140
  output?: OutputSpec;
111
141
  /** Raw passthrough for tool-specific knobs. */
@@ -161,6 +191,8 @@ export interface AgentSpec {
161
191
  parameters?: Record<string, string>;
162
192
  /** Files downloaded into the workspace before the agent starts; only references travel. */
163
193
  files?: InputFile[];
194
+ /** Session id of an earlier realtime run to continue: its saved conversation is restored and the definition's prompt is not sent. */
195
+ resumeSession?: string;
164
196
  }
165
197
  export interface AgentStatus {
166
198
  phase?: Phase;
@@ -173,6 +205,16 @@ export interface AgentStatus {
173
205
  output?: string;
174
206
  failureReason?: string;
175
207
  prUrl?: string;
208
+ /** Harness session id of this run; pass it as spec.resumeSession to continue the conversation. */
209
+ sessionId?: string;
210
+ /** Provider batch id while a batch-executed run is in flight. */
211
+ batchId?: string;
212
+ /** Provider the batch was submitted to. */
213
+ batchProvider?: string;
214
+ /** True once the batch timed out and the fallback Job started. */
215
+ batchFallback?: boolean;
216
+ /** Failed attempts to delete the batch's provider-side objects. */
217
+ batchCleanupAttempts?: number;
176
218
  }
177
219
  export interface Agent {
178
220
  apiVersion?: string;
@@ -181,3 +223,32 @@ export interface Agent {
181
223
  spec?: AgentSpec;
182
224
  status?: AgentStatus;
183
225
  }
226
+ export interface ModelInfo {
227
+ /** Model id to set as an AgentDefinition's or Agent's model. */
228
+ id?: string;
229
+ /** The vendor's human-readable name for the model. */
230
+ displayName?: string;
231
+ }
232
+ export interface VendorModels {
233
+ /** Agent CLI vendor the subsystem routes these model ids to. */
234
+ vendor?: string;
235
+ /** Provider API whose list-models endpoint was queried. */
236
+ provider?: string;
237
+ /** agent-secrets keys that were queried; an AgentDefinition can run these models when its resources.secrets maps one of them. */
238
+ secretRefs?: string[];
239
+ /** Why the last refresh could not list models with some of the keys; empty when every key answered. */
240
+ error?: string;
241
+ models?: ModelInfo[];
242
+ }
243
+ export interface ModelCatalogStatus {
244
+ /** RFC3339 timestamp of the last refresh. */
245
+ refreshedAt?: string;
246
+ vendors?: VendorModels[];
247
+ }
248
+ /** The models the subsystem can run, written by the controller from each vendor's list-models API. */
249
+ export interface ModelCatalog {
250
+ apiVersion?: string;
251
+ kind?: string;
252
+ metadata?: ObjectMeta;
253
+ status?: ModelCatalogStatus;
254
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@re-cinq/agent-contracts",
3
- "version": "0.12.0",
3
+ "version": "0.13.0",
4
4
  "description": "TypeScript types + client for the ai-agent-subsystem CRDs (Agent / Station / AgentDefinition). Types are generated from the D source so they cannot drift.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {