@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 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 **ModelCatalog** (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**, **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
+ }
@@ -1,3 +1,4 @@
1
1
  // Code generated by ai-agent-tsgen from the agentcore CRD structs. DO NOT EDIT.
2
2
  // Regenerate: dub run :tsgen -- emit <path>/types.generated.ts
3
- export {};
3
+ export const GROUP = "agents.re-cinq.com";
4
+ export const VERSION = "v1beta1";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@re-cinq/agent-contracts",
3
- "version": "0.13.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": {