@re-cinq/agent-contracts 0.12.0 → 0.14.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 +7 -3
- package/dist/client.d.ts +3 -3
- package/dist/client.js +10 -2
- package/dist/types.generated.d.ts +130 -0
- package/dist/types.generated.js +2 -1
- package/package.json +1 -1
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 **
|
|
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**, **ModelCatalog** and **AgentSpawner** (API group `agents.re-cinq.com/v1beta1`).
|
|
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, the `AgentSpawner`, `AgentSpawnerSpec` and `AgentSpawnerStatus` types, and the string-literal unions (`Phase`, `ConcurrencyPolicy`, `SpawnerConcurrencyPolicy`, `PermissionMode`, ...).
|
|
16
16
|
- **Constants**: `GROUP`, `VERSION`, `DEFAULT_NAMESPACE`.
|
|
17
|
-
- **`AgentContractsClient`** — create/read/list Agents
|
|
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.
|
|
@@ -82,6 +82,9 @@ const finished = await waitForAgent(client, run.metadata!.name!);
|
|
|
82
82
|
console.log(finished.status?.phase, finished.status?.prUrl);
|
|
83
83
|
```
|
|
84
84
|
|
|
85
|
+
`status.prUrl` is set when the Station's AgentDefinition has `spec.delivery.pullRequest`
|
|
86
|
+
(`DeliverySpec`, `PullRequestDelivery`): the run's commits are pushed and opened as a pull request.
|
|
87
|
+
|
|
85
88
|
### API surface
|
|
86
89
|
|
|
87
90
|
| Member | Purpose |
|
|
@@ -90,6 +93,7 @@ console.log(finished.status?.phase, finished.status?.prUrl);
|
|
|
90
93
|
| `createAgent(agent)` | Create one Agent run. |
|
|
91
94
|
| `getAgent(name)` | Read one Agent by name. |
|
|
92
95
|
| `findAgents(labelSelector)` | List Agents matching a Kubernetes label selector. |
|
|
96
|
+
| `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
97
|
| `applyStation(station)` | Server-side apply a Station. |
|
|
94
98
|
| `applyAgentDefinition(def)` | Server-side apply an AgentDefinition. |
|
|
95
99
|
| `isTerminal(agent)` | `true` once `status.phase` is `Succeeded` or `Failed`. |
|
package/dist/client.d.ts
CHANGED
|
@@ -1,6 +1,4 @@
|
|
|
1
|
-
import type { Agent, AgentDefinition, Station } from "./types.generated.js";
|
|
2
|
-
export declare const GROUP = "agents.re-cinq.com";
|
|
3
|
-
export declare const VERSION = "v1alpha1";
|
|
1
|
+
import type { Agent, AgentDefinition, ModelCatalog, Station } from "./types.generated.js";
|
|
4
2
|
export declare const DEFAULT_NAMESPACE = "ai-agents";
|
|
5
3
|
export interface KubeRequest {
|
|
6
4
|
method: "GET" | "POST" | "PATCH";
|
|
@@ -29,6 +27,8 @@ export declare class AgentContractsClient {
|
|
|
29
27
|
getAgent(name: string): Promise<Agent>;
|
|
30
28
|
/** List Agents matching a Kubernetes label selector. */
|
|
31
29
|
findAgents(labelSelector: string): Promise<Agent[]>;
|
|
30
|
+
/** Read the models the subsystem can run (the controller's `default` ModelCatalog). */
|
|
31
|
+
getModelCatalog(): Promise<ModelCatalog>;
|
|
32
32
|
/** Server-side apply an AgentDefinition (the UI uses this to push edited YAML). */
|
|
33
33
|
applyAgentDefinition(def: AgentDefinition): Promise<AgentDefinition>;
|
|
34
34
|
/** Server-side apply a Station. */
|
package/dist/client.js
CHANGED
|
@@ -2,11 +2,11 @@
|
|
|
2
2
|
// IO is injected as a KubeTransport so the client logic is deterministically
|
|
3
3
|
// testable with an in-memory fake (no cluster, no mocks). A concrete transport
|
|
4
4
|
// (fetch / @kubernetes/client-node) is supplied by the consumer (an orchestrator or UI).
|
|
5
|
+
import { GROUP, VERSION } from "./types.generated.js";
|
|
5
6
|
import { enforce, enforceHTTPSuccess } from "./enforce.js";
|
|
6
|
-
export const GROUP = "agents.re-cinq.com";
|
|
7
|
-
export const VERSION = "v1alpha1";
|
|
8
7
|
export const DEFAULT_NAMESPACE = "ai-agents";
|
|
9
8
|
const FIELD_MANAGER = "agent-contracts";
|
|
9
|
+
const MODEL_CATALOG_NAME = "default";
|
|
10
10
|
const TERMINAL_PHASES = ["Succeeded", "Failed"];
|
|
11
11
|
/** True once an Agent run has reached a terminal phase (Succeeded / Failed). */
|
|
12
12
|
export function isTerminal(agent) {
|
|
@@ -51,6 +51,14 @@ export class AgentContractsClient {
|
|
|
51
51
|
const list = enforceHTTPSuccess(res);
|
|
52
52
|
return list.items ?? [];
|
|
53
53
|
}
|
|
54
|
+
/** Read the models the subsystem can run (the controller's `default` ModelCatalog). */
|
|
55
|
+
async getModelCatalog() {
|
|
56
|
+
const res = await this.transport.request({
|
|
57
|
+
method: "GET",
|
|
58
|
+
path: `${namespacedPath("modelcatalogs", this.namespace)}/${MODEL_CATALOG_NAME}`,
|
|
59
|
+
});
|
|
60
|
+
return enforceHTTPSuccess(res);
|
|
61
|
+
}
|
|
54
62
|
/** Server-side apply an AgentDefinition (the UI uses this to push edited YAML). */
|
|
55
63
|
applyAgentDefinition(def) {
|
|
56
64
|
return this.apply("agentdefinitions", def);
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
export declare const GROUP = "agents.re-cinq.com";
|
|
2
|
+
export declare const VERSION = "v1beta1";
|
|
1
3
|
export type PermissionMode = "auto" | "bypass";
|
|
2
4
|
export type McpTransport = "stdio" | "http" | "sse";
|
|
3
5
|
export type OutputFormat = "text" | "json" | "stream-json";
|
|
@@ -5,6 +7,9 @@ export type SelectEvent = "tool_call" | "message" | "tool_result" | "result" | "
|
|
|
5
7
|
export type SelectRole = "assistant" | "user";
|
|
6
8
|
export type SinkType = "stdout" | "http" | "file";
|
|
7
9
|
export type ConcurrencyPolicy = "Allow" | "Forbid" | "Replace";
|
|
10
|
+
export type SpawnerConcurrencyPolicy = "Allow" | "Forbid";
|
|
11
|
+
export type Execution = "interactive" | "batch" | "realtime";
|
|
12
|
+
export type BatchTimeoutAction = "fail" | "fallback";
|
|
8
13
|
export type Phase = "Pending" | "Running" | "Succeeded" | "Failed";
|
|
9
14
|
export interface ObjectMeta {
|
|
10
15
|
name?: string;
|
|
@@ -15,6 +20,8 @@ export interface ObjectMeta {
|
|
|
15
20
|
creationTimestamp?: string;
|
|
16
21
|
labels?: Record<string, string>;
|
|
17
22
|
annotations?: Record<string, string>;
|
|
23
|
+
finalizers?: string[];
|
|
24
|
+
deletionTimestamp?: string;
|
|
18
25
|
}
|
|
19
26
|
export interface EnvVar {
|
|
20
27
|
name: string;
|
|
@@ -26,13 +33,24 @@ export interface SecretRef {
|
|
|
26
33
|
/** Allowlisted secret-store key. */
|
|
27
34
|
ref: string;
|
|
28
35
|
}
|
|
36
|
+
export interface McpHeader {
|
|
37
|
+
/** HTTP header name, e.g. X-API-Key. */
|
|
38
|
+
name: string;
|
|
39
|
+
/** Allowlisted secret-store key holding the header value. */
|
|
40
|
+
ref: string;
|
|
41
|
+
}
|
|
29
42
|
export interface McpServer {
|
|
30
43
|
name: string;
|
|
31
44
|
transport: McpTransport;
|
|
32
45
|
command?: string;
|
|
33
46
|
args?: string[];
|
|
34
47
|
url?: string;
|
|
48
|
+
/** Deprecated: use headers. Allowlisted secret-store key sent as the Authorization header. */
|
|
35
49
|
headers_secret?: string;
|
|
50
|
+
/** http/sse: headers whose values come from the secret store. */
|
|
51
|
+
headers?: McpHeader[];
|
|
52
|
+
/** stdio: environment variables for the server process whose values come from the secret store. */
|
|
53
|
+
env?: SecretRef[];
|
|
36
54
|
}
|
|
37
55
|
export interface RepoRef {
|
|
38
56
|
name: string;
|
|
@@ -94,6 +112,33 @@ export interface OutputSpec {
|
|
|
94
112
|
sinks?: OutputSink[];
|
|
95
113
|
watch?: OutputWatch[];
|
|
96
114
|
}
|
|
115
|
+
/** Open a pull request from the run's work branch; the push happens outside the agent container. */
|
|
116
|
+
export interface PullRequestDelivery {
|
|
117
|
+
/** Branch the pull request merges into. */
|
|
118
|
+
base: string;
|
|
119
|
+
/** Pull request title; {placeholder} tokens are filled from the Agent's parameters. */
|
|
120
|
+
titleTemplate: string;
|
|
121
|
+
/** Open the pull request as a draft. */
|
|
122
|
+
draft?: boolean;
|
|
123
|
+
/** GitHub REST API base URL; defaults to https://api.github.com. */
|
|
124
|
+
apiUrl?: string;
|
|
125
|
+
}
|
|
126
|
+
/** What happens to the run's work once the agent exits. */
|
|
127
|
+
export interface DeliverySpec {
|
|
128
|
+
pullRequest?: PullRequestDelivery;
|
|
129
|
+
}
|
|
130
|
+
export interface BatchSpec {
|
|
131
|
+
/** Minutes to wait for the batch result before onTimeout applies. */
|
|
132
|
+
timeoutMinutes?: number;
|
|
133
|
+
/** fail marks the Agent Failed; fallback reruns the work as a CLI Job. */
|
|
134
|
+
onTimeout?: BatchTimeoutAction;
|
|
135
|
+
/** Output token ceiling (max_tokens) for the batch request. */
|
|
136
|
+
maxTokens?: number;
|
|
137
|
+
}
|
|
138
|
+
export interface RealtimeSpec {
|
|
139
|
+
/** Minutes without a prompt or a running turn after which the session ends and its conversation is saved. */
|
|
140
|
+
idleTimeoutMinutes?: number;
|
|
141
|
+
}
|
|
97
142
|
/** The reusable recipe for a coding agent task. */
|
|
98
143
|
export interface AgentDefinitionSpec {
|
|
99
144
|
/** Human summary for operators. */
|
|
@@ -106,8 +151,12 @@ export interface AgentDefinitionSpec {
|
|
|
106
151
|
disallowed_tools?: string[];
|
|
107
152
|
permission_mode?: PermissionMode;
|
|
108
153
|
max_turns?: number;
|
|
154
|
+
execution?: Execution;
|
|
155
|
+
batch?: BatchSpec;
|
|
156
|
+
realtime?: RealtimeSpec;
|
|
109
157
|
resources?: AgentResources;
|
|
110
158
|
output?: OutputSpec;
|
|
159
|
+
delivery?: DeliverySpec;
|
|
111
160
|
/** Raw passthrough for tool-specific knobs. */
|
|
112
161
|
tool_config?: unknown;
|
|
113
162
|
}
|
|
@@ -161,6 +210,8 @@ export interface AgentSpec {
|
|
|
161
210
|
parameters?: Record<string, string>;
|
|
162
211
|
/** Files downloaded into the workspace before the agent starts; only references travel. */
|
|
163
212
|
files?: InputFile[];
|
|
213
|
+
/** Session id of an earlier realtime run to continue: its saved conversation is restored and the definition's prompt is not sent. */
|
|
214
|
+
resumeSession?: string;
|
|
164
215
|
}
|
|
165
216
|
export interface AgentStatus {
|
|
166
217
|
phase?: Phase;
|
|
@@ -172,7 +223,18 @@ export interface AgentStatus {
|
|
|
172
223
|
exitCode?: number;
|
|
173
224
|
output?: string;
|
|
174
225
|
failureReason?: string;
|
|
226
|
+
/** URL of the pull request the run opened (spec.delivery.pullRequest). */
|
|
175
227
|
prUrl?: string;
|
|
228
|
+
/** Harness session id of this run; pass it as spec.resumeSession to continue the conversation. */
|
|
229
|
+
sessionId?: string;
|
|
230
|
+
/** Provider batch id while a batch-executed run is in flight. */
|
|
231
|
+
batchId?: string;
|
|
232
|
+
/** Provider the batch was submitted to. */
|
|
233
|
+
batchProvider?: string;
|
|
234
|
+
/** True once the batch timed out and the fallback Job started. */
|
|
235
|
+
batchFallback?: boolean;
|
|
236
|
+
/** Failed attempts to delete the batch's provider-side objects. */
|
|
237
|
+
batchCleanupAttempts?: number;
|
|
176
238
|
}
|
|
177
239
|
export interface Agent {
|
|
178
240
|
apiVersion?: string;
|
|
@@ -181,3 +243,71 @@ export interface Agent {
|
|
|
181
243
|
spec?: AgentSpec;
|
|
182
244
|
status?: AgentStatus;
|
|
183
245
|
}
|
|
246
|
+
export interface ModelInfo {
|
|
247
|
+
/** Model id to set as an AgentDefinition's or Agent's model. */
|
|
248
|
+
id?: string;
|
|
249
|
+
/** The vendor's human-readable name for the model. */
|
|
250
|
+
displayName?: string;
|
|
251
|
+
}
|
|
252
|
+
export interface VendorModels {
|
|
253
|
+
/** Agent CLI vendor the subsystem routes these model ids to. */
|
|
254
|
+
vendor?: string;
|
|
255
|
+
/** Provider API whose list-models endpoint was queried. */
|
|
256
|
+
provider?: string;
|
|
257
|
+
/** agent-secrets keys that were queried; an AgentDefinition can run these models when its resources.secrets maps one of them. */
|
|
258
|
+
secretRefs?: string[];
|
|
259
|
+
/** Why the last refresh could not list models with some of the keys; empty when every key answered. */
|
|
260
|
+
error?: string;
|
|
261
|
+
models?: ModelInfo[];
|
|
262
|
+
}
|
|
263
|
+
export interface ModelCatalogStatus {
|
|
264
|
+
/** RFC3339 timestamp of the last refresh. */
|
|
265
|
+
refreshedAt?: string;
|
|
266
|
+
vendors?: VendorModels[];
|
|
267
|
+
}
|
|
268
|
+
/** The models the subsystem can run, written by the controller from each vendor's list-models API. */
|
|
269
|
+
export interface ModelCatalog {
|
|
270
|
+
apiVersion?: string;
|
|
271
|
+
kind?: string;
|
|
272
|
+
metadata?: ObjectMeta;
|
|
273
|
+
status?: ModelCatalogStatus;
|
|
274
|
+
}
|
|
275
|
+
/** Starts a run for each signed GitHub webhook delivery that matches. */
|
|
276
|
+
export interface GitHubTrigger {
|
|
277
|
+
/** Key in the agent-secrets Secret holding the webhook's HMAC secret. */
|
|
278
|
+
secretRef: string;
|
|
279
|
+
/** Deliveries that start a run, as <X-GitHub-Event>.<action> (issues.labeled); an event without an action by its name alone. */
|
|
280
|
+
events: string[];
|
|
281
|
+
/** Only issues carrying this label start a run; for issues.labeled, only when it is the label just added. */
|
|
282
|
+
label?: string;
|
|
283
|
+
/** Only deliveries from this owner/name repository start a run. */
|
|
284
|
+
repository?: string;
|
|
285
|
+
}
|
|
286
|
+
/** Creates an Agent in a Station on a cron schedule, on GitHub webhook deliveries, or both. */
|
|
287
|
+
export interface AgentSpawnerSpec {
|
|
288
|
+
/** The Station each spawned Agent runs in. */
|
|
289
|
+
stationRef: string;
|
|
290
|
+
/** Five-field cron expression (minute hour day-of-month month day-of-week), evaluated in UTC. */
|
|
291
|
+
schedule?: string;
|
|
292
|
+
/** Starts a run for each matching GitHub webhook delivery. */
|
|
293
|
+
github?: GitHubTrigger;
|
|
294
|
+
/** Copied verbatim into every spawned Agent's spec.parameters. */
|
|
295
|
+
parameters?: Record<string, string>;
|
|
296
|
+
/** Allow starts a run on every tick; Forbid skips a tick while an Agent this spawner created is not finished. */
|
|
297
|
+
concurrencyPolicy?: SpawnerConcurrencyPolicy;
|
|
298
|
+
/** True stops new runs; runs already started are left alone. */
|
|
299
|
+
suspend?: boolean;
|
|
300
|
+
}
|
|
301
|
+
export interface AgentSpawnerStatus {
|
|
302
|
+
/** RFC3339 schedule time of the last tick handled, whether it created an Agent or was skipped. */
|
|
303
|
+
lastScheduleTime?: string;
|
|
304
|
+
/** Name of the last Agent this spawner created. */
|
|
305
|
+
lastAgent?: string;
|
|
306
|
+
}
|
|
307
|
+
export interface AgentSpawner {
|
|
308
|
+
apiVersion?: string;
|
|
309
|
+
kind?: string;
|
|
310
|
+
metadata?: ObjectMeta;
|
|
311
|
+
spec?: AgentSpawnerSpec;
|
|
312
|
+
status?: AgentSpawnerStatus;
|
|
313
|
+
}
|
package/dist/types.generated.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@re-cinq/agent-contracts",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.14.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": {
|