@re-cinq/agent-contracts 0.3.0 → 0.8.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 +102 -0
- package/dist/client.js +6 -14
- package/dist/enforce.d.ts +7 -0
- package/dist/enforce.js +15 -0
- package/dist/index.d.ts +1 -0
- package/dist/index.js +1 -0
- package/dist/types.generated.d.ts +3 -1
- package/package.json +4 -4
package/README.md
ADDED
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
# @re-cinq/agent-contracts
|
|
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`).
|
|
4
|
+
|
|
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
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install @re-cinq/agent-contracts
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
## What you get
|
|
14
|
+
|
|
15
|
+
- **Types** for every resource and nested field: `Agent`, `Station`, `AgentDefinition`, their `*Spec`/`*Status` shapes, and the string-literal unions (`Phase`, `ConcurrencyPolicy`, `PermissionMode`, ...).
|
|
16
|
+
- **Constants**: `GROUP`, `VERSION`, `DEFAULT_NAMESPACE`.
|
|
17
|
+
- **`AgentContractsClient`** — create/read/list Agents and server-side-apply Stations and AgentDefinitions.
|
|
18
|
+
- **Helpers**: `isTerminal(agent)` and `waitForAgent(client, name, options?)`.
|
|
19
|
+
|
|
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.
|
|
21
|
+
|
|
22
|
+
## Types only
|
|
23
|
+
|
|
24
|
+
If you just need to type Kubernetes objects (e.g. to validate YAML or build a UI form), import the types and ignore the client:
|
|
25
|
+
|
|
26
|
+
```ts
|
|
27
|
+
import type { AgentDefinition, Station, Agent, Phase } from "@re-cinq/agent-contracts";
|
|
28
|
+
|
|
29
|
+
const recipe: AgentDefinition = {
|
|
30
|
+
metadata: { name: "bug-fixer" },
|
|
31
|
+
spec: {
|
|
32
|
+
model: "claude-sonnet-4-6",
|
|
33
|
+
prompt: "Fix the bug described in issue {issue}.",
|
|
34
|
+
allowed_tools: ["bash", "edit"],
|
|
35
|
+
},
|
|
36
|
+
};
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Using the client
|
|
40
|
+
|
|
41
|
+
The client speaks to the Kubernetes API through a `KubeTransport` — one method that turns a `KubeRequest` into a `KubeResponse`. Here is a minimal `fetch`-based transport:
|
|
42
|
+
|
|
43
|
+
```ts
|
|
44
|
+
import { AgentContractsClient, type KubeTransport } from "@re-cinq/agent-contracts";
|
|
45
|
+
|
|
46
|
+
const transport: KubeTransport = {
|
|
47
|
+
async request({ method, path, query, body, contentType }) {
|
|
48
|
+
const url = new URL(path, "https://your-kube-apiserver");
|
|
49
|
+
for (const [key, value] of Object.entries(query ?? {})) {
|
|
50
|
+
url.searchParams.set(key, value);
|
|
51
|
+
}
|
|
52
|
+
const res = await fetch(url, {
|
|
53
|
+
method,
|
|
54
|
+
headers: {
|
|
55
|
+
Authorization: `Bearer ${process.env.KUBE_TOKEN}`,
|
|
56
|
+
...(body ? { "Content-Type": contentType ?? "application/json" } : {}),
|
|
57
|
+
},
|
|
58
|
+
body: body ? JSON.stringify(body) : undefined,
|
|
59
|
+
});
|
|
60
|
+
return { status: res.status, body: await res.json() };
|
|
61
|
+
},
|
|
62
|
+
};
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Then launch a run and wait for it to finish:
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
import { AgentContractsClient, waitForAgent } from "@re-cinq/agent-contracts";
|
|
69
|
+
|
|
70
|
+
const client = new AgentContractsClient(transport, "ai-agents");
|
|
71
|
+
|
|
72
|
+
const run = await client.createAgent({
|
|
73
|
+
metadata: { generateName: "fix-bug-" },
|
|
74
|
+
spec: {
|
|
75
|
+
stationRef: "bug-fixer",
|
|
76
|
+
targetRepo: "re-cinq/ai-agent-subsystem",
|
|
77
|
+
parameters: { issue: "123" },
|
|
78
|
+
},
|
|
79
|
+
});
|
|
80
|
+
|
|
81
|
+
const finished = await waitForAgent(client, run.metadata!.name!);
|
|
82
|
+
console.log(finished.status?.phase, finished.status?.prUrl);
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### API surface
|
|
86
|
+
|
|
87
|
+
| Member | Purpose |
|
|
88
|
+
| --- | --- |
|
|
89
|
+
| `new AgentContractsClient(transport, namespace?)` | Bind a transport to a namespace (defaults to `ai-agents`). |
|
|
90
|
+
| `createAgent(agent)` | Create one Agent run. |
|
|
91
|
+
| `getAgent(name)` | Read one Agent by name. |
|
|
92
|
+
| `findAgents(labelSelector)` | List Agents matching a Kubernetes label selector. |
|
|
93
|
+
| `applyStation(station)` | Server-side apply a Station. |
|
|
94
|
+
| `applyAgentDefinition(def)` | Server-side apply an AgentDefinition. |
|
|
95
|
+
| `isTerminal(agent)` | `true` once `status.phase` is `Succeeded` or `Failed`. |
|
|
96
|
+
| `waitForAgent(client, name, options?)` | Poll `getAgent` until terminal; `options` are `attempts`, `intervalMs`, and an injectable `sleep`. |
|
|
97
|
+
|
|
98
|
+
A non-2xx response throws an `Error` with the status code and body.
|
|
99
|
+
|
|
100
|
+
## License
|
|
101
|
+
|
|
102
|
+
Apache-2.0
|
package/dist/client.js
CHANGED
|
@@ -2,6 +2,7 @@
|
|
|
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 (the Floor / UI).
|
|
5
|
+
import { enforce, enforceHTTPSuccess } from "./enforce.js";
|
|
5
6
|
export const GROUP = "agents.re-cinq.com";
|
|
6
7
|
export const VERSION = "v1alpha1";
|
|
7
8
|
export const DEFAULT_NAMESPACE = "ai-agents";
|
|
@@ -15,12 +16,6 @@ export function isTerminal(agent) {
|
|
|
15
16
|
function namespacedPath(plural, namespace) {
|
|
16
17
|
return `/apis/${GROUP}/${VERSION}/namespaces/${namespace}/${plural}`;
|
|
17
18
|
}
|
|
18
|
-
function expectOk(res) {
|
|
19
|
-
if (res.status < 200 || res.status >= 300) {
|
|
20
|
-
throw new Error(`kube request failed (${res.status}): ${JSON.stringify(res.body)}`);
|
|
21
|
-
}
|
|
22
|
-
return res.body;
|
|
23
|
-
}
|
|
24
19
|
/** Typed client for the Agent / Station / AgentDefinition resources. */
|
|
25
20
|
export class AgentContractsClient {
|
|
26
21
|
transport;
|
|
@@ -36,7 +31,7 @@ export class AgentContractsClient {
|
|
|
36
31
|
path: namespacedPath("agents", this.namespace),
|
|
37
32
|
body: { apiVersion: `${GROUP}/${VERSION}`, kind: "Agent", ...agent },
|
|
38
33
|
});
|
|
39
|
-
return
|
|
34
|
+
return enforceHTTPSuccess(res);
|
|
40
35
|
}
|
|
41
36
|
/** Read one Agent by name. */
|
|
42
37
|
async getAgent(name) {
|
|
@@ -44,7 +39,7 @@ export class AgentContractsClient {
|
|
|
44
39
|
method: "GET",
|
|
45
40
|
path: `${namespacedPath("agents", this.namespace)}/${name}`,
|
|
46
41
|
});
|
|
47
|
-
return
|
|
42
|
+
return enforceHTTPSuccess(res);
|
|
48
43
|
}
|
|
49
44
|
/** List Agents matching a Kubernetes label selector. */
|
|
50
45
|
async findAgents(labelSelector) {
|
|
@@ -53,7 +48,7 @@ export class AgentContractsClient {
|
|
|
53
48
|
path: namespacedPath("agents", this.namespace),
|
|
54
49
|
query: { labelSelector },
|
|
55
50
|
});
|
|
56
|
-
const list =
|
|
51
|
+
const list = enforceHTTPSuccess(res);
|
|
57
52
|
return list.items ?? [];
|
|
58
53
|
}
|
|
59
54
|
/** Server-side apply an AgentDefinition (the UI uses this to push edited YAML). */
|
|
@@ -65,10 +60,7 @@ export class AgentContractsClient {
|
|
|
65
60
|
return this.apply("stations", station);
|
|
66
61
|
}
|
|
67
62
|
async apply(plural, resource) {
|
|
68
|
-
const name = resource.metadata?.name;
|
|
69
|
-
if (!name) {
|
|
70
|
-
throw new Error(`apply ${plural}: metadata.name is required`);
|
|
71
|
-
}
|
|
63
|
+
const name = enforce(resource.metadata?.name, `apply ${plural}: metadata.name is required`);
|
|
72
64
|
const res = await this.transport.request({
|
|
73
65
|
method: "PATCH",
|
|
74
66
|
path: `${namespacedPath(plural, this.namespace)}/${name}`,
|
|
@@ -76,7 +68,7 @@ export class AgentContractsClient {
|
|
|
76
68
|
body: resource,
|
|
77
69
|
contentType: "application/apply-patch+yaml",
|
|
78
70
|
});
|
|
79
|
-
return
|
|
71
|
+
return enforceHTTPSuccess(res);
|
|
80
72
|
}
|
|
81
73
|
}
|
|
82
74
|
const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
/** Throws unless `value` is truthy, returns the narrowed value (like D's `enforce`). */
|
|
2
|
+
export declare function enforce<T>(value: T, message: string): NonNullable<T>;
|
|
3
|
+
/** Throws unless the response status is 2xx; returns the body on success. */
|
|
4
|
+
export declare function enforceHTTPSuccess(res: {
|
|
5
|
+
status: number;
|
|
6
|
+
body: unknown;
|
|
7
|
+
}): unknown;
|
package/dist/enforce.js
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
// D-style std.exception bouncers: either the condition holds or you're thrown
|
|
2
|
+
// out on the spot. No polite if-throw ceremonies.
|
|
3
|
+
/** Throws unless `value` is truthy, returns the narrowed value (like D's `enforce`). */
|
|
4
|
+
export function enforce(value, message) {
|
|
5
|
+
if (!value)
|
|
6
|
+
throw new Error(message);
|
|
7
|
+
return value;
|
|
8
|
+
}
|
|
9
|
+
/** Throws unless the response status is 2xx; returns the body on success. */
|
|
10
|
+
export function enforceHTTPSuccess(res) {
|
|
11
|
+
if (res.status < 200 || res.status >= 300) {
|
|
12
|
+
throw new Error(`kube request failed (${res.status}): ${JSON.stringify(res.body)}`);
|
|
13
|
+
}
|
|
14
|
+
return res.body;
|
|
15
|
+
}
|
package/dist/index.d.ts
CHANGED
package/dist/index.js
CHANGED
|
@@ -45,6 +45,8 @@ export interface AgentResources {
|
|
|
45
45
|
secrets?: SecretRef[];
|
|
46
46
|
mcp_servers?: McpServer[];
|
|
47
47
|
repos?: RepoRef[];
|
|
48
|
+
skills?: string[];
|
|
49
|
+
skills_source?: string;
|
|
48
50
|
}
|
|
49
51
|
export interface OutputSelector {
|
|
50
52
|
event: SelectEvent;
|
|
@@ -72,7 +74,7 @@ export interface AgentDefinitionSpec {
|
|
|
72
74
|
/** Model id (e.g. claude-sonnet-4-6). If omitted, the runtime default is used. */
|
|
73
75
|
model?: string;
|
|
74
76
|
/** Task template; {placeholder} tokens are filled from an Agent's parameters. */
|
|
75
|
-
prompt
|
|
77
|
+
prompt: string;
|
|
76
78
|
allowed_tools?: string[];
|
|
77
79
|
disallowed_tools?: string[];
|
|
78
80
|
permission_mode?: PermissionMode;
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@re-cinq/agent-contracts",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.8.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": {
|
|
@@ -25,9 +25,9 @@
|
|
|
25
25
|
"test:coverage": "vitest run --coverage"
|
|
26
26
|
},
|
|
27
27
|
"devDependencies": {
|
|
28
|
-
"@vitest/coverage-v8": "^
|
|
29
|
-
"typescript": "^
|
|
30
|
-
"vitest": "^
|
|
28
|
+
"@vitest/coverage-v8": "^4.1.10",
|
|
29
|
+
"typescript": "^7.0.2",
|
|
30
|
+
"vitest": "^4.1.10"
|
|
31
31
|
},
|
|
32
32
|
"publishConfig": {
|
|
33
33
|
"access": "public"
|