@re-cinq/agent-contracts 0.13.0 → 0.15.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 +21 -2
- package/dist/client.d.ts +0 -2
- package/dist/client.js +1 -2
- package/dist/types.generated.d.ts +79 -1
- 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**, **AgentDefinition** 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,7 +12,7 @@ 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, the `ModelCatalog`, `ModelCatalogStatus`, `VendorModels` and `ModelInfo` types, 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
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?)`.
|
|
@@ -82,6 +82,25 @@ const finished = await waitForAgent(client, run.metadata!.name!);
|
|
|
82
82
|
console.log(finished.status?.phase, finished.status?.prUrl);
|
|
83
83
|
```
|
|
84
84
|
|
|
85
|
+
An AgentDefinition is a reusable recipe, so a run's own repositories, conversation, output, secrets and
|
|
86
|
+
env go on `spec` of the Agent (`repos`, `conversation`, `output`, `secrets`, `env`) and win over the
|
|
87
|
+
recipe's value when set:
|
|
88
|
+
|
|
89
|
+
```ts
|
|
90
|
+
await client.createAgent({
|
|
91
|
+
metadata: { generateName: "review-" },
|
|
92
|
+
spec: {
|
|
93
|
+
stationRef: "repo-reviewer",
|
|
94
|
+
repos: [{ name: "app", url: "https://github.com/example/app", token_secret: "RUN_1_TOKEN" }],
|
|
95
|
+
conversation: { id: "eng-101", pin: "eng-101" },
|
|
96
|
+
output: { sinks: [{ type: "http", url: "https://collector.example.com/runs/eng-101" }] },
|
|
97
|
+
},
|
|
98
|
+
});
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
`status.prUrl` is set when the Station's AgentDefinition has `spec.delivery.pullRequest`
|
|
102
|
+
(`DeliverySpec`, `PullRequestDelivery`): the run's commits are pushed and opened as a pull request.
|
|
103
|
+
|
|
85
104
|
### API surface
|
|
86
105
|
|
|
87
106
|
| Member | Purpose |
|
package/dist/client.d.ts
CHANGED
|
@@ -1,6 +1,4 @@
|
|
|
1
1
|
import type { Agent, AgentDefinition, ModelCatalog, Station } from "./types.generated.js";
|
|
2
|
-
export declare const GROUP = "agents.re-cinq.com";
|
|
3
|
-
export declare const VERSION = "v1alpha1";
|
|
4
2
|
export declare const DEFAULT_NAMESPACE = "ai-agents";
|
|
5
3
|
export interface KubeRequest {
|
|
6
4
|
method: "GET" | "POST" | "PATCH";
|
package/dist/client.js
CHANGED
|
@@ -2,9 +2,8 @@
|
|
|
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";
|
|
10
9
|
const MODEL_CATALOG_NAME = "default";
|
|
@@ -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,7 @@ 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";
|
|
8
11
|
export type Execution = "interactive" | "batch" | "realtime";
|
|
9
12
|
export type BatchTimeoutAction = "fail" | "fallback";
|
|
10
13
|
export type Phase = "Pending" | "Running" | "Succeeded" | "Failed";
|
|
@@ -109,6 +112,30 @@ export interface OutputSpec {
|
|
|
109
112
|
sinks?: OutputSink[];
|
|
110
113
|
watch?: OutputWatch[];
|
|
111
114
|
}
|
|
115
|
+
/** Where one run's output goes; sinks and select replace the AgentDefinition's when set, watch merges by event. */
|
|
116
|
+
export interface RunOutput {
|
|
117
|
+
/** Sinks for this run; when set they replace the recipe's sinks. */
|
|
118
|
+
sinks?: OutputSink[];
|
|
119
|
+
/** Which events reach the sinks; when set it replaces the recipe's selectors. */
|
|
120
|
+
select?: OutputSelector[];
|
|
121
|
+
/** Files this run produces. An entry replaces the recipe's watch of the same event (so a run can give a recipe's watch its own upload); other events are added. */
|
|
122
|
+
watch?: OutputWatch[];
|
|
123
|
+
}
|
|
124
|
+
/** Open a pull request from the run's work branch; the push happens outside the agent container. */
|
|
125
|
+
export interface PullRequestDelivery {
|
|
126
|
+
/** Branch the pull request merges into. */
|
|
127
|
+
base: string;
|
|
128
|
+
/** Pull request title; {placeholder} tokens are filled from the Agent's parameters. */
|
|
129
|
+
titleTemplate: string;
|
|
130
|
+
/** Open the pull request as a draft. */
|
|
131
|
+
draft?: boolean;
|
|
132
|
+
/** GitHub REST API base URL; defaults to https://api.github.com. */
|
|
133
|
+
apiUrl?: string;
|
|
134
|
+
}
|
|
135
|
+
/** What happens to the run's work once the agent exits. */
|
|
136
|
+
export interface DeliverySpec {
|
|
137
|
+
pullRequest?: PullRequestDelivery;
|
|
138
|
+
}
|
|
112
139
|
export interface BatchSpec {
|
|
113
140
|
/** Minutes to wait for the batch result before onTimeout applies. */
|
|
114
141
|
timeoutMinutes?: number;
|
|
@@ -138,6 +165,7 @@ export interface AgentDefinitionSpec {
|
|
|
138
165
|
realtime?: RealtimeSpec;
|
|
139
166
|
resources?: AgentResources;
|
|
140
167
|
output?: OutputSpec;
|
|
168
|
+
delivery?: DeliverySpec;
|
|
141
169
|
/** Raw passthrough for tool-specific knobs. */
|
|
142
170
|
tool_config?: unknown;
|
|
143
171
|
}
|
|
@@ -176,7 +204,7 @@ export interface InputFile {
|
|
|
176
204
|
/** Secret key holding the header block sent with the download. */
|
|
177
205
|
headers_secret?: string;
|
|
178
206
|
}
|
|
179
|
-
/** One run of a recipe in a Station. */
|
|
207
|
+
/** One run of a recipe in a Station. The AgentDefinition is the reusable recipe; what belongs to a single run (repos, conversation, output, secrets, env) can be given here and wins over the recipe's value when set, so one AgentDefinition serves many Agents. */
|
|
180
208
|
export interface AgentSpec {
|
|
181
209
|
/** The Station to run in (which selects the recipe). */
|
|
182
210
|
stationRef: string;
|
|
@@ -193,6 +221,16 @@ export interface AgentSpec {
|
|
|
193
221
|
files?: InputFile[];
|
|
194
222
|
/** Session id of an earlier realtime run to continue: its saved conversation is restored and the definition's prompt is not sent. */
|
|
195
223
|
resumeSession?: string;
|
|
224
|
+
/** Repositories to clone for this run; when set they replace the AgentDefinition's resources.repos. */
|
|
225
|
+
repos?: RepoRef[];
|
|
226
|
+
/** Conversation to continue and the id to save under; each field set here wins over the same field of the AgentDefinition's resources.conversation. */
|
|
227
|
+
conversation?: ConversationRef;
|
|
228
|
+
/** Where this run's output goes; see RunOutput for how each field combines with the AgentDefinition's output. */
|
|
229
|
+
output?: RunOutput;
|
|
230
|
+
/** Secrets exposed to this run, such as per-run credentials; an entry replaces the AgentDefinition's resources.secrets entry of the same name, others are added. */
|
|
231
|
+
secrets?: SecretRef[];
|
|
232
|
+
/** Environment values for this run, such as ones derived from its inputs; an entry replaces the AgentDefinition's resources.env entry of the same name, others are added. */
|
|
233
|
+
env?: EnvVar[];
|
|
196
234
|
}
|
|
197
235
|
export interface AgentStatus {
|
|
198
236
|
phase?: Phase;
|
|
@@ -204,6 +242,7 @@ export interface AgentStatus {
|
|
|
204
242
|
exitCode?: number;
|
|
205
243
|
output?: string;
|
|
206
244
|
failureReason?: string;
|
|
245
|
+
/** URL of the pull request the run opened (spec.delivery.pullRequest). */
|
|
207
246
|
prUrl?: string;
|
|
208
247
|
/** Harness session id of this run; pass it as spec.resumeSession to continue the conversation. */
|
|
209
248
|
sessionId?: string;
|
|
@@ -252,3 +291,42 @@ export interface ModelCatalog {
|
|
|
252
291
|
metadata?: ObjectMeta;
|
|
253
292
|
status?: ModelCatalogStatus;
|
|
254
293
|
}
|
|
294
|
+
/** Starts a run for each signed GitHub webhook delivery that matches. */
|
|
295
|
+
export interface GitHubTrigger {
|
|
296
|
+
/** Key in the agent-secrets Secret holding the webhook's HMAC secret. */
|
|
297
|
+
secretRef: string;
|
|
298
|
+
/** Deliveries that start a run, as <X-GitHub-Event>.<action> (issues.labeled); an event without an action by its name alone. */
|
|
299
|
+
events: string[];
|
|
300
|
+
/** Only issues carrying this label start a run; for issues.labeled, only when it is the label just added. */
|
|
301
|
+
label?: string;
|
|
302
|
+
/** Only deliveries from this owner/name repository start a run. */
|
|
303
|
+
repository?: string;
|
|
304
|
+
}
|
|
305
|
+
/** Creates an Agent in a Station on a cron schedule, on GitHub webhook deliveries, or both. */
|
|
306
|
+
export interface AgentSpawnerSpec {
|
|
307
|
+
/** The Station each spawned Agent runs in. */
|
|
308
|
+
stationRef: string;
|
|
309
|
+
/** Five-field cron expression (minute hour day-of-month month day-of-week), evaluated in UTC. */
|
|
310
|
+
schedule?: string;
|
|
311
|
+
/** Starts a run for each matching GitHub webhook delivery. */
|
|
312
|
+
github?: GitHubTrigger;
|
|
313
|
+
/** Copied verbatim into every spawned Agent's spec.parameters. */
|
|
314
|
+
parameters?: Record<string, string>;
|
|
315
|
+
/** Allow starts a run on every tick; Forbid skips a tick while an Agent this spawner created is not finished. */
|
|
316
|
+
concurrencyPolicy?: SpawnerConcurrencyPolicy;
|
|
317
|
+
/** True stops new runs; runs already started are left alone. */
|
|
318
|
+
suspend?: boolean;
|
|
319
|
+
}
|
|
320
|
+
export interface AgentSpawnerStatus {
|
|
321
|
+
/** RFC3339 schedule time of the last tick handled, whether it created an Agent or was skipped. */
|
|
322
|
+
lastScheduleTime?: string;
|
|
323
|
+
/** Name of the last Agent this spawner created. */
|
|
324
|
+
lastAgent?: string;
|
|
325
|
+
}
|
|
326
|
+
export interface AgentSpawner {
|
|
327
|
+
apiVersion?: string;
|
|
328
|
+
kind?: string;
|
|
329
|
+
metadata?: ObjectMeta;
|
|
330
|
+
spec?: AgentSpawnerSpec;
|
|
331
|
+
status?: AgentSpawnerStatus;
|
|
332
|
+
}
|
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.15.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": {
|