@re-cinq/agent-contracts 0.3.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/dist/client.d.ts +44 -0
- package/dist/client.js +96 -0
- package/dist/index.d.ts +2 -0
- package/dist/index.js +2 -0
- package/dist/types.generated.d.ts +142 -0
- package/dist/types.generated.js +3 -0
- package/package.json +35 -0
package/dist/client.d.ts
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
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";
|
|
4
|
+
export declare const DEFAULT_NAMESPACE = "ai-agents";
|
|
5
|
+
export interface KubeRequest {
|
|
6
|
+
method: "GET" | "POST" | "PATCH";
|
|
7
|
+
path: string;
|
|
8
|
+
query?: Record<string, string>;
|
|
9
|
+
body?: unknown;
|
|
10
|
+
contentType?: string;
|
|
11
|
+
}
|
|
12
|
+
export interface KubeResponse {
|
|
13
|
+
status: number;
|
|
14
|
+
body: unknown;
|
|
15
|
+
}
|
|
16
|
+
export interface KubeTransport {
|
|
17
|
+
request(req: KubeRequest): Promise<KubeResponse>;
|
|
18
|
+
}
|
|
19
|
+
/** True once an Agent run has reached a terminal phase (Succeeded / Failed). */
|
|
20
|
+
export declare function isTerminal(agent: Agent): boolean;
|
|
21
|
+
/** Typed client for the Agent / Station / AgentDefinition resources. */
|
|
22
|
+
export declare class AgentContractsClient {
|
|
23
|
+
private readonly transport;
|
|
24
|
+
private readonly namespace;
|
|
25
|
+
constructor(transport: KubeTransport, namespace?: string);
|
|
26
|
+
/** Create one Agent run. */
|
|
27
|
+
createAgent(agent: Agent): Promise<Agent>;
|
|
28
|
+
/** Read one Agent by name. */
|
|
29
|
+
getAgent(name: string): Promise<Agent>;
|
|
30
|
+
/** List Agents matching a Kubernetes label selector. */
|
|
31
|
+
findAgents(labelSelector: string): Promise<Agent[]>;
|
|
32
|
+
/** Server-side apply an AgentDefinition (the UI uses this to push edited YAML). */
|
|
33
|
+
applyAgentDefinition(def: AgentDefinition): Promise<AgentDefinition>;
|
|
34
|
+
/** Server-side apply a Station. */
|
|
35
|
+
applyStation(station: Station): Promise<Station>;
|
|
36
|
+
private apply;
|
|
37
|
+
}
|
|
38
|
+
export interface WaitOptions {
|
|
39
|
+
attempts?: number;
|
|
40
|
+
intervalMs?: number;
|
|
41
|
+
sleep?: (ms: number) => Promise<void>;
|
|
42
|
+
}
|
|
43
|
+
/** Poll `getAgent` until the run reaches a terminal phase, or attempts run out. */
|
|
44
|
+
export declare function waitForAgent(client: Pick<AgentContractsClient, "getAgent">, name: string, options?: WaitOptions): Promise<Agent>;
|
package/dist/client.js
ADDED
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
// Thin, typed client over the Kubernetes API for the agents.re-cinq.com CRDs.
|
|
2
|
+
// IO is injected as a KubeTransport so the client logic is deterministically
|
|
3
|
+
// testable with an in-memory fake (no cluster, no mocks). A concrete transport
|
|
4
|
+
// (fetch / @kubernetes/client-node) is supplied by the consumer (the Floor / UI).
|
|
5
|
+
export const GROUP = "agents.re-cinq.com";
|
|
6
|
+
export const VERSION = "v1alpha1";
|
|
7
|
+
export const DEFAULT_NAMESPACE = "ai-agents";
|
|
8
|
+
const FIELD_MANAGER = "lore-ui";
|
|
9
|
+
const TERMINAL_PHASES = ["Succeeded", "Failed"];
|
|
10
|
+
/** True once an Agent run has reached a terminal phase (Succeeded / Failed). */
|
|
11
|
+
export function isTerminal(agent) {
|
|
12
|
+
const phase = agent.status?.phase;
|
|
13
|
+
return phase !== undefined && TERMINAL_PHASES.includes(phase);
|
|
14
|
+
}
|
|
15
|
+
function namespacedPath(plural, namespace) {
|
|
16
|
+
return `/apis/${GROUP}/${VERSION}/namespaces/${namespace}/${plural}`;
|
|
17
|
+
}
|
|
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
|
+
/** Typed client for the Agent / Station / AgentDefinition resources. */
|
|
25
|
+
export class AgentContractsClient {
|
|
26
|
+
transport;
|
|
27
|
+
namespace;
|
|
28
|
+
constructor(transport, namespace = DEFAULT_NAMESPACE) {
|
|
29
|
+
this.transport = transport;
|
|
30
|
+
this.namespace = namespace;
|
|
31
|
+
}
|
|
32
|
+
/** Create one Agent run. */
|
|
33
|
+
async createAgent(agent) {
|
|
34
|
+
const res = await this.transport.request({
|
|
35
|
+
method: "POST",
|
|
36
|
+
path: namespacedPath("agents", this.namespace),
|
|
37
|
+
body: { apiVersion: `${GROUP}/${VERSION}`, kind: "Agent", ...agent },
|
|
38
|
+
});
|
|
39
|
+
return expectOk(res);
|
|
40
|
+
}
|
|
41
|
+
/** Read one Agent by name. */
|
|
42
|
+
async getAgent(name) {
|
|
43
|
+
const res = await this.transport.request({
|
|
44
|
+
method: "GET",
|
|
45
|
+
path: `${namespacedPath("agents", this.namespace)}/${name}`,
|
|
46
|
+
});
|
|
47
|
+
return expectOk(res);
|
|
48
|
+
}
|
|
49
|
+
/** List Agents matching a Kubernetes label selector. */
|
|
50
|
+
async findAgents(labelSelector) {
|
|
51
|
+
const res = await this.transport.request({
|
|
52
|
+
method: "GET",
|
|
53
|
+
path: namespacedPath("agents", this.namespace),
|
|
54
|
+
query: { labelSelector },
|
|
55
|
+
});
|
|
56
|
+
const list = expectOk(res);
|
|
57
|
+
return list.items ?? [];
|
|
58
|
+
}
|
|
59
|
+
/** Server-side apply an AgentDefinition (the UI uses this to push edited YAML). */
|
|
60
|
+
applyAgentDefinition(def) {
|
|
61
|
+
return this.apply("agentdefinitions", def);
|
|
62
|
+
}
|
|
63
|
+
/** Server-side apply a Station. */
|
|
64
|
+
applyStation(station) {
|
|
65
|
+
return this.apply("stations", station);
|
|
66
|
+
}
|
|
67
|
+
async apply(plural, resource) {
|
|
68
|
+
const name = resource.metadata?.name;
|
|
69
|
+
if (!name) {
|
|
70
|
+
throw new Error(`apply ${plural}: metadata.name is required`);
|
|
71
|
+
}
|
|
72
|
+
const res = await this.transport.request({
|
|
73
|
+
method: "PATCH",
|
|
74
|
+
path: `${namespacedPath(plural, this.namespace)}/${name}`,
|
|
75
|
+
query: { fieldManager: FIELD_MANAGER, force: "true" },
|
|
76
|
+
body: resource,
|
|
77
|
+
contentType: "application/apply-patch+yaml",
|
|
78
|
+
});
|
|
79
|
+
return expectOk(res);
|
|
80
|
+
}
|
|
81
|
+
}
|
|
82
|
+
const realSleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
|
|
83
|
+
/** Poll `getAgent` until the run reaches a terminal phase, or attempts run out. */
|
|
84
|
+
export async function waitForAgent(client, name, options = {}) {
|
|
85
|
+
const attempts = options.attempts ?? 600;
|
|
86
|
+
const intervalMs = options.intervalMs ?? 2000;
|
|
87
|
+
const sleep = options.sleep ?? realSleep;
|
|
88
|
+
for (let attempt = 0; attempt < attempts; attempt++) {
|
|
89
|
+
const agent = await client.getAgent(name);
|
|
90
|
+
if (isTerminal(agent)) {
|
|
91
|
+
return agent;
|
|
92
|
+
}
|
|
93
|
+
await sleep(intervalMs);
|
|
94
|
+
}
|
|
95
|
+
throw new Error(`agent ${name} did not reach a terminal phase within ${attempts} attempts`);
|
|
96
|
+
}
|
package/dist/index.d.ts
ADDED
package/dist/index.js
ADDED
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
export type PermissionMode = "auto" | "bypass";
|
|
2
|
+
export type McpTransport = "stdio" | "http" | "sse";
|
|
3
|
+
export type OutputFormat = "text" | "json" | "stream-json";
|
|
4
|
+
export type SelectEvent = "tool_call" | "message" | "tool_result" | "result" | "usage";
|
|
5
|
+
export type SelectRole = "assistant" | "user";
|
|
6
|
+
export type SinkType = "stdout" | "http" | "file";
|
|
7
|
+
export type ConcurrencyPolicy = "Allow" | "Forbid" | "Replace";
|
|
8
|
+
export type Phase = "Pending" | "Running" | "Succeeded" | "Failed";
|
|
9
|
+
export interface ObjectMeta {
|
|
10
|
+
name?: string;
|
|
11
|
+
generateName?: string;
|
|
12
|
+
namespace?: string;
|
|
13
|
+
uid?: string;
|
|
14
|
+
resourceVersion?: string;
|
|
15
|
+
labels?: Record<string, string>;
|
|
16
|
+
annotations?: Record<string, string>;
|
|
17
|
+
}
|
|
18
|
+
export interface EnvVar {
|
|
19
|
+
name: string;
|
|
20
|
+
value: string;
|
|
21
|
+
}
|
|
22
|
+
export interface SecretRef {
|
|
23
|
+
/** Environment variable name to expose the secret as. */
|
|
24
|
+
name: string;
|
|
25
|
+
/** Allowlisted secret-store key. */
|
|
26
|
+
ref: string;
|
|
27
|
+
}
|
|
28
|
+
export interface McpServer {
|
|
29
|
+
name: string;
|
|
30
|
+
transport: McpTransport;
|
|
31
|
+
command?: string;
|
|
32
|
+
args?: string[];
|
|
33
|
+
url?: string;
|
|
34
|
+
headers_secret?: string;
|
|
35
|
+
}
|
|
36
|
+
export interface RepoRef {
|
|
37
|
+
name: string;
|
|
38
|
+
url: string;
|
|
39
|
+
ref?: string;
|
|
40
|
+
path?: string;
|
|
41
|
+
token_secret?: string;
|
|
42
|
+
}
|
|
43
|
+
export interface AgentResources {
|
|
44
|
+
env?: EnvVar[];
|
|
45
|
+
secrets?: SecretRef[];
|
|
46
|
+
mcp_servers?: McpServer[];
|
|
47
|
+
repos?: RepoRef[];
|
|
48
|
+
}
|
|
49
|
+
export interface OutputSelector {
|
|
50
|
+
event: SelectEvent;
|
|
51
|
+
tool?: string;
|
|
52
|
+
role?: SelectRole;
|
|
53
|
+
contains?: string;
|
|
54
|
+
}
|
|
55
|
+
export interface OutputSink {
|
|
56
|
+
type: SinkType;
|
|
57
|
+
url?: string;
|
|
58
|
+
headers_secret?: string;
|
|
59
|
+
path?: string;
|
|
60
|
+
}
|
|
61
|
+
export interface OutputSpec {
|
|
62
|
+
format?: OutputFormat;
|
|
63
|
+
/** JSON Schema validating the result. */
|
|
64
|
+
schema?: unknown;
|
|
65
|
+
select?: OutputSelector[];
|
|
66
|
+
sinks?: OutputSink[];
|
|
67
|
+
}
|
|
68
|
+
/** The reusable recipe for a coding agent task. */
|
|
69
|
+
export interface AgentDefinitionSpec {
|
|
70
|
+
/** Human summary for operators. */
|
|
71
|
+
description?: string;
|
|
72
|
+
/** Model id (e.g. claude-sonnet-4-6). If omitted, the runtime default is used. */
|
|
73
|
+
model?: string;
|
|
74
|
+
/** Task template; {placeholder} tokens are filled from an Agent's parameters. */
|
|
75
|
+
prompt?: string;
|
|
76
|
+
allowed_tools?: string[];
|
|
77
|
+
disallowed_tools?: string[];
|
|
78
|
+
permission_mode?: PermissionMode;
|
|
79
|
+
max_turns?: number;
|
|
80
|
+
resources?: AgentResources;
|
|
81
|
+
output?: OutputSpec;
|
|
82
|
+
/** Raw passthrough for tool-specific knobs. */
|
|
83
|
+
tool_config?: unknown;
|
|
84
|
+
}
|
|
85
|
+
export interface AgentDefinition {
|
|
86
|
+
apiVersion?: string;
|
|
87
|
+
kind?: string;
|
|
88
|
+
metadata?: ObjectMeta;
|
|
89
|
+
spec?: AgentDefinitionSpec;
|
|
90
|
+
}
|
|
91
|
+
/** The runtime template that pairs a recipe with a Pod template. */
|
|
92
|
+
export interface StationSpec {
|
|
93
|
+
/** Name of the AgentDefinition this Station runs. */
|
|
94
|
+
agentDefRef: string;
|
|
95
|
+
/** Wall-clock limit per run; becomes the Job's activeDeadlineSeconds. */
|
|
96
|
+
deadlineMinutes?: number;
|
|
97
|
+
successfulRunsHistoryLimit?: number;
|
|
98
|
+
failedRunsHistoryLimit?: number;
|
|
99
|
+
/** Max Agents of this Station running at once; 0 is unlimited. A Pending Agent waits while at the limit. */
|
|
100
|
+
maxConcurrentRuns?: number;
|
|
101
|
+
/** At the limit: Allow queues (default), Forbid caps at one, Replace cancels the oldest run for the new one. */
|
|
102
|
+
concurrencyPolicy?: ConcurrencyPolicy;
|
|
103
|
+
/** Standard Kubernetes PodTemplateSpec; the container named "agent" is wired with the recipe. */
|
|
104
|
+
template: unknown;
|
|
105
|
+
}
|
|
106
|
+
export interface Station {
|
|
107
|
+
apiVersion?: string;
|
|
108
|
+
kind?: string;
|
|
109
|
+
metadata?: ObjectMeta;
|
|
110
|
+
spec?: StationSpec;
|
|
111
|
+
}
|
|
112
|
+
/** One run of a recipe in a Station. */
|
|
113
|
+
export interface AgentSpec {
|
|
114
|
+
/** The Station to run in (which selects the recipe). */
|
|
115
|
+
stationRef: string;
|
|
116
|
+
/** External id for correlation. */
|
|
117
|
+
taskId?: string;
|
|
118
|
+
/** GitHub repo in owner/name form. */
|
|
119
|
+
targetRepo?: string;
|
|
120
|
+
branch?: string;
|
|
121
|
+
/** Per-run values; fill the prompt {placeholder} tokens and pass to the agent. */
|
|
122
|
+
parameters?: Record<string, string>;
|
|
123
|
+
}
|
|
124
|
+
export interface AgentStatus {
|
|
125
|
+
phase?: Phase;
|
|
126
|
+
jobName?: string;
|
|
127
|
+
/** RFC3339 timestamp when the run began. */
|
|
128
|
+
startedAt?: string;
|
|
129
|
+
/** RFC3339 timestamp when the run ended. */
|
|
130
|
+
completedAt?: string;
|
|
131
|
+
exitCode?: number;
|
|
132
|
+
output?: string;
|
|
133
|
+
failureReason?: string;
|
|
134
|
+
prUrl?: string;
|
|
135
|
+
}
|
|
136
|
+
export interface Agent {
|
|
137
|
+
apiVersion?: string;
|
|
138
|
+
kind?: string;
|
|
139
|
+
metadata?: ObjectMeta;
|
|
140
|
+
spec?: AgentSpec;
|
|
141
|
+
status?: AgentStatus;
|
|
142
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@re-cinq/agent-contracts",
|
|
3
|
+
"version": "0.3.0",
|
|
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
|
+
"license": "Apache-2.0",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/re-cinq/ai-agent-subsystem.git",
|
|
9
|
+
"directory": "packages/agent-contracts"
|
|
10
|
+
},
|
|
11
|
+
"type": "module",
|
|
12
|
+
"main": "./dist/index.js",
|
|
13
|
+
"types": "./dist/index.d.ts",
|
|
14
|
+
"exports": {
|
|
15
|
+
".": {
|
|
16
|
+
"types": "./dist/index.d.ts",
|
|
17
|
+
"default": "./dist/index.js"
|
|
18
|
+
}
|
|
19
|
+
},
|
|
20
|
+
"files": ["dist"],
|
|
21
|
+
"scripts": {
|
|
22
|
+
"build": "tsc -p tsconfig.json",
|
|
23
|
+
"typecheck": "tsc --noEmit -p tsconfig.json",
|
|
24
|
+
"test": "vitest run",
|
|
25
|
+
"test:coverage": "vitest run --coverage"
|
|
26
|
+
},
|
|
27
|
+
"devDependencies": {
|
|
28
|
+
"@vitest/coverage-v8": "^2.1.0",
|
|
29
|
+
"typescript": "^5.6.0",
|
|
30
|
+
"vitest": "^2.1.0"
|
|
31
|
+
},
|
|
32
|
+
"publishConfig": {
|
|
33
|
+
"access": "public"
|
|
34
|
+
}
|
|
35
|
+
}
|