@re-cinq/agent-contracts 0.13.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 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,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 |
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,21 @@ export interface OutputSpec {
109
112
  sinks?: OutputSink[];
110
113
  watch?: OutputWatch[];
111
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
+ }
112
130
  export interface BatchSpec {
113
131
  /** Minutes to wait for the batch result before onTimeout applies. */
114
132
  timeoutMinutes?: number;
@@ -138,6 +156,7 @@ export interface AgentDefinitionSpec {
138
156
  realtime?: RealtimeSpec;
139
157
  resources?: AgentResources;
140
158
  output?: OutputSpec;
159
+ delivery?: DeliverySpec;
141
160
  /** Raw passthrough for tool-specific knobs. */
142
161
  tool_config?: unknown;
143
162
  }
@@ -204,6 +223,7 @@ export interface AgentStatus {
204
223
  exitCode?: number;
205
224
  output?: string;
206
225
  failureReason?: string;
226
+ /** URL of the pull request the run opened (spec.delivery.pullRequest). */
207
227
  prUrl?: string;
208
228
  /** Harness session id of this run; pass it as spec.resumeSession to continue the conversation. */
209
229
  sessionId?: string;
@@ -252,3 +272,42 @@ export interface ModelCatalog {
252
272
  metadata?: ObjectMeta;
253
273
  status?: ModelCatalogStatus;
254
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
+ }
@@ -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.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": {