robisie 0.1.0 → 0.1.2
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/CHANGELOG.md +79 -0
- package/README.md +109 -14
- package/dist/active-recovery.d.ts +58 -0
- package/dist/active-recovery.js +143 -0
- package/dist/agents.d.ts +34 -0
- package/dist/agents.js +77 -16
- package/dist/attempt-identity.d.ts +21 -0
- package/dist/attempt-identity.js +39 -0
- package/dist/ci-failure-result.d.ts +23 -0
- package/dist/ci-failure-result.js +90 -0
- package/dist/claude-headless.d.ts +7 -0
- package/dist/claude-headless.js +28 -0
- package/dist/cli.d.ts +17 -0
- package/dist/cli.js +54 -14
- package/dist/commands.d.ts +18 -0
- package/dist/commands.js +195 -88
- package/dist/constants.d.ts +32 -0
- package/dist/constants.js +3 -3
- package/dist/context.d.ts +24 -0
- package/dist/context.js +22 -6
- package/dist/dependency-readiness.d.ts +13 -0
- package/dist/dependency-readiness.js +80 -0
- package/dist/dispatch-scope.d.ts +18 -0
- package/dist/dispatch-scope.js +46 -0
- package/dist/done-evidence.d.ts +31 -0
- package/dist/done-evidence.js +216 -0
- package/dist/engine-config.d.ts +65 -0
- package/dist/engine-config.js +139 -0
- package/dist/fsops.d.ts +87 -0
- package/dist/fsops.js +117 -24
- package/dist/helpers.d.ts +15 -0
- package/dist/helpers.js +268 -45
- package/dist/intent-rules/admission.d.ts +10 -0
- package/dist/intent-rules/admission.js +35 -0
- package/dist/intent-rules/done-when-roles.d.ts +21 -0
- package/dist/intent-rules/done-when-roles.js +101 -0
- package/dist/intent-rules/hooks.d.ts +29 -0
- package/dist/intent-rules/hooks.js +23 -0
- package/dist/k3-codex-role.d.ts +20 -0
- package/dist/k3-codex-role.js +68 -0
- package/dist/manifest.d.ts +41 -0
- package/dist/manifest.js +59 -14
- package/dist/mcp.d.ts +18 -0
- package/dist/mcp.js +117 -40
- package/dist/opencode-result.d.ts +19 -0
- package/dist/opencode-result.js +136 -0
- package/dist/opencode-review-guard.d.ts +1 -0
- package/dist/opencode-review-guard.js +19 -0
- package/dist/opencode-session-export.d.ts +5 -0
- package/dist/opencode-session-export.js +28 -0
- package/dist/outcome-moves.d.ts +15 -0
- package/dist/outcome-moves.js +39 -0
- package/dist/planer-client.d.ts +214 -0
- package/dist/planer-client.js +351 -0
- package/dist/restart-recovery.d.ts +47 -0
- package/dist/restart-recovery.js +70 -0
- package/dist/review-source-packet.d.ts +17 -0
- package/dist/review-source-packet.js +44 -0
- package/dist/role-registry.d.ts +25 -0
- package/dist/role-registry.js +91 -0
- package/dist/role-results.d.ts +15 -0
- package/dist/role-results.js +42 -0
- package/dist/roles.d.ts +30 -0
- package/dist/roles.js +20 -16
- package/dist/seed-validation.d.ts +28 -0
- package/dist/seed-validation.js +294 -0
- package/dist/selection-result.d.ts +44 -0
- package/dist/selection-result.js +144 -0
- package/dist/sparse-policy.d.ts +8 -0
- package/dist/sparse-policy.js +49 -0
- package/dist/tester-identity.d.ts +11 -0
- package/dist/tester-identity.js +53 -0
- package/dist/worker-env.d.ts +5 -0
- package/dist/worker-env.js +34 -0
- package/docs/ENGINE-API.md +88 -0
- package/docs/ENGINE-CONFIG.md +113 -0
- package/docs/README.en.md +142 -20
- package/docs/README.md +144 -20
- package/docs/RELEASE-0.1.0.md +81 -8
- package/docs/RELEASE-0.1.1.md +110 -0
- package/helpers/ceo-client-launcher-mcp.mjs +36 -8
- package/helpers/client-spawn-session.sh +181 -0
- package/helpers/client-spawn.sh +825 -0
- package/package.json +9 -4
- package/roles/ceo-client.md +3 -2
- package/roles/manager-builder-client.md +18 -4
- package/roles/quality-officer-client.md +20 -6
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
import { z } from "zod";
|
|
2
|
+
/** No environment, filesystem, DB or Keychain reads. Pass Ctx.origin/fetch and ROBISIE_KEY explicitly. */
|
|
3
|
+
export type PlanerClientConfig = ({
|
|
4
|
+
origin: string;
|
|
5
|
+
endpoint?: never;
|
|
6
|
+
} | {
|
|
7
|
+
endpoint: string;
|
|
8
|
+
origin?: never;
|
|
9
|
+
}) & {
|
|
10
|
+
token: string;
|
|
11
|
+
fetch?: typeof fetch;
|
|
12
|
+
deadlineMs?: number;
|
|
13
|
+
};
|
|
14
|
+
type Operation = "connect" | "close" | "list_projects" | "list_tracks" | "list_tasks" | "get_task" | "reserve_task" | "update_task" | "append_detail" | "close_decision_matter" | "get_review_snapshot" | "accept_review" | "create_track" | "create_task";
|
|
15
|
+
type Failure = "INVALID_CONFIG" | "INVALID_ARGUMENT" | "NOT_CONNECTED" | "CLOSED" | "CONTRACT_VERSION" | "INVALID_RESPONSE" | "DETAILS_READ_ERROR" | "TOOL_ERROR" | "UNAUTHORIZED" | "FORBIDDEN" | "RATE_LIMITED" | "HTTP_ERROR" | "RPC_ERROR" | "TRANSPORT_ERROR" | "TIMEOUT";
|
|
16
|
+
/** Fixed reason only. In particular, never attach SDK message, cause, raw body or caller arguments. */
|
|
17
|
+
export declare class PlanerClientError extends Error {
|
|
18
|
+
readonly code: Failure;
|
|
19
|
+
readonly operation: Operation;
|
|
20
|
+
/** A write may have reached the server: caller must read/decide before another write. */
|
|
21
|
+
readonly uncertain: boolean;
|
|
22
|
+
constructor(code: Failure, operation: Operation,
|
|
23
|
+
/** A write may have reached the server: caller must read/decide before another write. */
|
|
24
|
+
uncertain?: boolean, diagnostic?: {
|
|
25
|
+
plannerCode?: string;
|
|
26
|
+
requestId?: string;
|
|
27
|
+
});
|
|
28
|
+
readonly plannerCode?: string;
|
|
29
|
+
readonly requestId?: string;
|
|
30
|
+
}
|
|
31
|
+
declare const jsonObject: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
|
|
32
|
+
declare const projectSchema: z.ZodObject<{
|
|
33
|
+
id: z.ZodUUID;
|
|
34
|
+
name: z.ZodString;
|
|
35
|
+
slug: z.ZodString;
|
|
36
|
+
}, z.core.$strip>;
|
|
37
|
+
declare const trackSchema: z.ZodObject<{
|
|
38
|
+
id: z.ZodUUID;
|
|
39
|
+
projectId: z.ZodUUID;
|
|
40
|
+
name: z.ZodString;
|
|
41
|
+
position: z.ZodNumber;
|
|
42
|
+
}, z.core.$strip>;
|
|
43
|
+
declare const taskSchema: z.ZodObject<{
|
|
44
|
+
id: z.ZodUUID;
|
|
45
|
+
projectId: z.ZodUUID;
|
|
46
|
+
trackId: z.ZodUUID;
|
|
47
|
+
title: z.ZodString;
|
|
48
|
+
status: z.ZodEnum<{
|
|
49
|
+
ready: "ready";
|
|
50
|
+
in_review: "in_review";
|
|
51
|
+
in_progress: "in_progress";
|
|
52
|
+
delivered: "delivered";
|
|
53
|
+
blocked: "blocked";
|
|
54
|
+
done: "done";
|
|
55
|
+
draft: "draft";
|
|
56
|
+
}>;
|
|
57
|
+
assignee: z.ZodNullable<z.ZodString>;
|
|
58
|
+
dependsOn: z.ZodArray<z.ZodUUID>;
|
|
59
|
+
}, z.core.$strip>;
|
|
60
|
+
declare const echoSchema: z.ZodObject<{
|
|
61
|
+
id: z.ZodUUID;
|
|
62
|
+
title: z.ZodString;
|
|
63
|
+
status: z.ZodEnum<{
|
|
64
|
+
ready: "ready";
|
|
65
|
+
in_review: "in_review";
|
|
66
|
+
in_progress: "in_progress";
|
|
67
|
+
delivered: "delivered";
|
|
68
|
+
blocked: "blocked";
|
|
69
|
+
done: "done";
|
|
70
|
+
draft: "draft";
|
|
71
|
+
}>;
|
|
72
|
+
trackId: z.ZodUUID;
|
|
73
|
+
updatedAt: z.ZodISODateTime;
|
|
74
|
+
}, z.core.$strip>;
|
|
75
|
+
declare const createTaskSchema: z.ZodObject<{
|
|
76
|
+
id: z.ZodUUID;
|
|
77
|
+
title: z.ZodString;
|
|
78
|
+
status: z.ZodEnum<{
|
|
79
|
+
ready: "ready";
|
|
80
|
+
in_review: "in_review";
|
|
81
|
+
in_progress: "in_progress";
|
|
82
|
+
delivered: "delivered";
|
|
83
|
+
blocked: "blocked";
|
|
84
|
+
done: "done";
|
|
85
|
+
draft: "draft";
|
|
86
|
+
}>;
|
|
87
|
+
trackId: z.ZodUUID;
|
|
88
|
+
updatedAt: z.ZodISODateTime;
|
|
89
|
+
similarOpenCards: z.ZodArray<z.ZodObject<{
|
|
90
|
+
id: z.ZodUUID;
|
|
91
|
+
title: z.ZodString;
|
|
92
|
+
track: z.ZodString;
|
|
93
|
+
status: z.ZodEnum<{
|
|
94
|
+
ready: "ready";
|
|
95
|
+
in_review: "in_review";
|
|
96
|
+
in_progress: "in_progress";
|
|
97
|
+
delivered: "delivered";
|
|
98
|
+
blocked: "blocked";
|
|
99
|
+
done: "done";
|
|
100
|
+
draft: "draft";
|
|
101
|
+
}>;
|
|
102
|
+
score: z.ZodNumber;
|
|
103
|
+
}, z.core.$strip>>;
|
|
104
|
+
}, z.core.$strip>;
|
|
105
|
+
declare const reviewSnapshotSchema: z.ZodObject<{
|
|
106
|
+
cardId: z.ZodUUID;
|
|
107
|
+
projectId: z.ZodUUID;
|
|
108
|
+
submissionId: z.ZodUUID;
|
|
109
|
+
snapshot: z.ZodString;
|
|
110
|
+
label: z.ZodLiteral<"recenzja innym kluczem; dostawca deklarowany">;
|
|
111
|
+
}, z.core.$strip>;
|
|
112
|
+
declare const acceptReviewInput: z.ZodObject<{
|
|
113
|
+
id: z.ZodUUID;
|
|
114
|
+
cardId: z.ZodUUID;
|
|
115
|
+
projectId: z.ZodUUID;
|
|
116
|
+
submissionId: z.ZodUUID;
|
|
117
|
+
snapshot: z.ZodString;
|
|
118
|
+
providerDeclared: z.ZodString;
|
|
119
|
+
}, z.core.$strict>;
|
|
120
|
+
export type ReviewSnapshot = z.infer<typeof reviewSnapshotSchema>;
|
|
121
|
+
export type AcceptReviewInput = z.infer<typeof acceptReviewInput>;
|
|
122
|
+
declare const reservationSchema: z.ZodObject<{
|
|
123
|
+
id: z.ZodUUID;
|
|
124
|
+
status: z.ZodEnum<{
|
|
125
|
+
ready: "ready";
|
|
126
|
+
in_review: "in_review";
|
|
127
|
+
in_progress: "in_progress";
|
|
128
|
+
delivered: "delivered";
|
|
129
|
+
blocked: "blocked";
|
|
130
|
+
done: "done";
|
|
131
|
+
draft: "draft";
|
|
132
|
+
}>;
|
|
133
|
+
assignee: z.ZodNullable<z.ZodString>;
|
|
134
|
+
trackId: z.ZodUUID;
|
|
135
|
+
updatedAt: z.ZodISODateTime;
|
|
136
|
+
}, z.core.$strip>;
|
|
137
|
+
declare const appendSchema: z.ZodObject<{
|
|
138
|
+
id: z.ZodUUID;
|
|
139
|
+
title: z.ZodString;
|
|
140
|
+
status: z.ZodEnum<{
|
|
141
|
+
ready: "ready";
|
|
142
|
+
in_review: "in_review";
|
|
143
|
+
in_progress: "in_progress";
|
|
144
|
+
delivered: "delivered";
|
|
145
|
+
blocked: "blocked";
|
|
146
|
+
done: "done";
|
|
147
|
+
draft: "draft";
|
|
148
|
+
}>;
|
|
149
|
+
trackId: z.ZodUUID;
|
|
150
|
+
updatedAt: z.ZodISODateTime;
|
|
151
|
+
appendedKeys: z.ZodArray<z.ZodString>;
|
|
152
|
+
}, z.core.$strip>;
|
|
153
|
+
declare const closeSchema: z.ZodObject<{
|
|
154
|
+
outcome: z.ZodEnum<{
|
|
155
|
+
CLOSED: "CLOSED";
|
|
156
|
+
ALREADY_CLOSED: "ALREADY_CLOSED";
|
|
157
|
+
CONFLICT: "CONFLICT";
|
|
158
|
+
NOT_APPLIED: "NOT_APPLIED";
|
|
159
|
+
}>;
|
|
160
|
+
cardId: z.ZodUUID;
|
|
161
|
+
matterId: z.ZodString;
|
|
162
|
+
matter: z.ZodNullable<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
|
|
163
|
+
}, z.core.$strip>;
|
|
164
|
+
export type PlanerTask = z.infer<typeof taskSchema> & {
|
|
165
|
+
details?: z.infer<typeof jsonObject> | null;
|
|
166
|
+
availableDetailsKeys?: string[] | null;
|
|
167
|
+
};
|
|
168
|
+
export type PlanerTaskWithReadiness = PlanerTask & {
|
|
169
|
+
depsReady: boolean;
|
|
170
|
+
};
|
|
171
|
+
export type AppendDetailResult = {
|
|
172
|
+
write: z.infer<typeof appendSchema>;
|
|
173
|
+
/** Write confirmation survives a failed readback; never repeat the append to repair a read. */
|
|
174
|
+
readback: {
|
|
175
|
+
ok: true;
|
|
176
|
+
task: PlanerTask | null;
|
|
177
|
+
} | {
|
|
178
|
+
ok: false;
|
|
179
|
+
error: PlanerClientError;
|
|
180
|
+
};
|
|
181
|
+
};
|
|
182
|
+
export type CloseDecisionResult = Omit<z.infer<typeof closeSchema>, "matter"> & {
|
|
183
|
+
isError: boolean;
|
|
184
|
+
};
|
|
185
|
+
/** Existing MCP operations only. No auto-connect, retry, CAS emulation or runtime cutover. */
|
|
186
|
+
export declare class PlanerClient {
|
|
187
|
+
#private;
|
|
188
|
+
constructor(config: unknown);
|
|
189
|
+
connect(): Promise<void>;
|
|
190
|
+
close(): Promise<void>;
|
|
191
|
+
listProjects(args?: unknown): Promise<z.infer<typeof projectSchema>[]>;
|
|
192
|
+
listTracks(args: unknown): Promise<z.infer<typeof trackSchema>[]>;
|
|
193
|
+
createTrack(args: unknown): Promise<z.infer<typeof trackSchema>>;
|
|
194
|
+
createTask(args: unknown): Promise<z.infer<typeof createTaskSchema>>;
|
|
195
|
+
listTasks(args: unknown): Promise<PlanerTaskWithReadiness[]>;
|
|
196
|
+
getTask(args: unknown): Promise<PlanerTask | null>;
|
|
197
|
+
reserveTask(args: unknown): Promise<z.infer<typeof reservationSchema>>;
|
|
198
|
+
/** Server snapshot of an in_review card; does not confirm enforced policy or code/model provenance.
|
|
199
|
+
* Rejects malformed/mismatched responses with INVALID_RESPONSE, uncertain=false. */
|
|
200
|
+
getReviewSnapshot(args: unknown): Promise<ReviewSnapshot>;
|
|
201
|
+
/** Server owns policy, authenticated actor and atomic receipt/delivered write. providerDeclared is
|
|
202
|
+
* only a declaration, not proof of model execution. No retry, update_task fallback or snapshot refresh.
|
|
203
|
+
* Strict input: matching id/cardId, UUIDs, lowercase 64-hex snapshot, trimmed 1–200 character declaration.
|
|
204
|
+
* Local validation fails with INVALID_ARGUMENT/uncertain=false; failures after sending are uncertain.
|
|
205
|
+
* After an uncertain write, caller must explicitly getTask({id, include:['review_receipt']}) and decide. */
|
|
206
|
+
acceptReview(args: unknown): Promise<z.infer<typeof echoSchema>>;
|
|
207
|
+
/** For draft promotion, pass {status:'ready', expected:{status:'draft'}}. Server owns CAS/permissions. */
|
|
208
|
+
updateTask(args: unknown): Promise<z.infer<typeof echoSchema>>;
|
|
209
|
+
/** Flat server merge; null is literal. No deep merge, chunking, append guard or implicit retry. */
|
|
210
|
+
appendDetail(args: unknown): Promise<AppendDetailResult>;
|
|
211
|
+
/** full/owner_validator authority stays on the server. Non-CLOSED outcomes retain isError. */
|
|
212
|
+
closeDecisionMatter(args: unknown): Promise<CloseDecisionResult>;
|
|
213
|
+
}
|
|
214
|
+
export {};
|
|
@@ -0,0 +1,351 @@
|
|
|
1
|
+
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
|
|
2
|
+
import { StreamableHTTPClientTransport, StreamableHTTPError } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
|
|
3
|
+
import { CallToolResultSchema, ErrorCode, McpError } from "@modelcontextprotocol/sdk/types.js";
|
|
4
|
+
import { z } from "zod";
|
|
5
|
+
import { CONTRACT_VERSION_HEADER, KEY_PATTERN, PACKAGE_NAME, PACKAGE_VERSION, mcpUrl } from "./constants.js";
|
|
6
|
+
import { assertCompatible } from "./mcp.js";
|
|
7
|
+
/** Fixed reason only. In particular, never attach SDK message, cause, raw body or caller arguments. */
|
|
8
|
+
export class PlanerClientError extends Error {
|
|
9
|
+
code;
|
|
10
|
+
operation;
|
|
11
|
+
uncertain;
|
|
12
|
+
constructor(code, operation,
|
|
13
|
+
/** A write may have reached the server: caller must read/decide before another write. */
|
|
14
|
+
uncertain = false, diagnostic) {
|
|
15
|
+
super(uncertain ? "Wynik zapisu niepewny. Odczytaj stan i podejmij decyzję przed kolejnym zapisem." : "Operacja Planera nie powiodła się.");
|
|
16
|
+
this.code = code;
|
|
17
|
+
this.operation = operation;
|
|
18
|
+
this.uncertain = uncertain;
|
|
19
|
+
this.name = "PlanerClientError";
|
|
20
|
+
if (diagnostic?.plannerCode !== undefined)
|
|
21
|
+
this.plannerCode = diagnostic.plannerCode;
|
|
22
|
+
if (diagnostic?.requestId !== undefined)
|
|
23
|
+
this.requestId = diagnostic.requestId;
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
const status = z.enum(["draft", "ready", "in_progress", "in_review", "blocked", "delivered", "done"]);
|
|
27
|
+
const uuid = z.uuid();
|
|
28
|
+
const keys = z.array(z.string());
|
|
29
|
+
const jsonObject = z.record(z.string(), z.json());
|
|
30
|
+
const boundedObject = jsonObject.refine(value => new TextEncoder().encode(JSON.stringify(value)).byteLength <= 10_000);
|
|
31
|
+
const freeText = z.string().max(2000);
|
|
32
|
+
const name = z.string().min(1).max(500);
|
|
33
|
+
const date = z.iso.datetime({ offset: true });
|
|
34
|
+
const projectSchema = z.object({ id: uuid, name: z.string(), slug: z.string() });
|
|
35
|
+
const trackSchema = z.object({ id: uuid, projectId: uuid, name: z.string(), position: z.number().int() });
|
|
36
|
+
const taskSchema = z.object({ id: uuid, projectId: uuid, trackId: uuid, title: z.string(), status,
|
|
37
|
+
assignee: z.string().nullable(), dependsOn: z.array(uuid) });
|
|
38
|
+
const echoSchema = z.object({ id: uuid, title: z.string(), status, trackId: uuid, updatedAt: date });
|
|
39
|
+
const createTrackInput = z.strictObject({ projectId: uuid, name, color: z.string().max(50).optional() });
|
|
40
|
+
const createTaskInput = z.strictObject({ projectId: uuid, trackId: uuid, title: name,
|
|
41
|
+
status: z.enum([...status.options, "spec", "plan", "w_pracy", "do_akceptacji", "wdrożone", "zrobione", "zablokowane"]).optional(),
|
|
42
|
+
details: jsonObject.nullable().optional(), specRef: freeText.nullable().optional(),
|
|
43
|
+
assignee: freeText.nullable().optional(), rob: freeText.nullable().optional(), dependsOn: z.array(uuid).max(200).optional() });
|
|
44
|
+
const createTaskSchema = echoSchema.extend({ similarOpenCards: z.array(z.object({
|
|
45
|
+
id: uuid, title: z.string(), track: z.string(), status, score: z.number().min(0).max(1),
|
|
46
|
+
})) });
|
|
47
|
+
const reviewSnapshotInput = z.strictObject({ id: uuid });
|
|
48
|
+
const reviewSnapshotSchema = z.object({ cardId: uuid, projectId: uuid, submissionId: uuid,
|
|
49
|
+
snapshot: z.string().regex(/^[a-f0-9]{64}$/), label: z.literal("recenzja innym kluczem; dostawca deklarowany") });
|
|
50
|
+
const acceptReviewInput = z.strictObject({ id: uuid, cardId: uuid, projectId: uuid, submissionId: uuid,
|
|
51
|
+
snapshot: z.string().regex(/^[a-f0-9]{64}$/), providerDeclared: z.string().trim().min(1).max(200) })
|
|
52
|
+
.refine(value => value.id === value.cardId);
|
|
53
|
+
// reserve_task still transfers full server PlannerTask/details; only these fields leave this adapter.
|
|
54
|
+
const reservationSchema = z.object({ id: uuid, status, assignee: z.string().nullable(), trackId: uuid, updatedAt: date });
|
|
55
|
+
const appendSchema = echoSchema.extend({ appendedKeys: keys });
|
|
56
|
+
const listInput = z.strictObject({ projectId: uuid, trackId: uuid.optional(), statuses: z.array(status).optional(), detailsKeys: keys });
|
|
57
|
+
const getInput = z.strictObject({ id: uuid, include: keys });
|
|
58
|
+
const reserveInput = z.strictObject({ id: uuid, assignee: freeText.nullable().optional() });
|
|
59
|
+
const updateInput = z.strictObject({ id: uuid, title: name.optional(), status: status.optional(),
|
|
60
|
+
expected: z.strictObject({ status }).optional(), details: jsonObject.nullable().optional(),
|
|
61
|
+
specRef: freeText.nullable().optional(), assignee: freeText.nullable().optional(), rob: freeText.nullable().optional(),
|
|
62
|
+
dependsOn: z.array(uuid).max(200).optional() });
|
|
63
|
+
const appendInput = z.strictObject({ id: uuid, patch: boundedObject });
|
|
64
|
+
const closeInput = z.strictObject({ id: uuid, matterId: z.string().regex(/^[0-9a-f]{16}$/), expected: boundedObject })
|
|
65
|
+
.refine(value => Object.keys(value.expected).length > 0
|
|
66
|
+
&& !(typeof value.expected.closedAt === "string" && value.expected.closedAt.length > 0)
|
|
67
|
+
&& (value.expected.id === undefined || value.expected.id === value.matterId));
|
|
68
|
+
const closeSchema = z.object({ outcome: z.enum(["CLOSED", "ALREADY_CLOSED", "CONFLICT", "NOT_APPLIED"]),
|
|
69
|
+
cardId: uuid, matterId: z.string().regex(/^[0-9a-f]{16}$/), matter: jsonObject.nullable() });
|
|
70
|
+
const updateFailure = z.object({ code: z.literal("PLANNER_UPDATE_FAILED"), requestId: uuid, message: z.string() });
|
|
71
|
+
const tooLargeFailure = z.object({ code: z.literal("TASK_RESPONSE_TOO_LARGE"), message: z.string() });
|
|
72
|
+
const runFailure = z.object({ requestId: uuid,
|
|
73
|
+
errorClass: z.enum(["Error", "TypeError", "RangeError", "SyntaxError", "AggregateError", "DrizzleQueryError", "DatabaseError"]),
|
|
74
|
+
causeMessage: z.string(), code: z.string().regex(/^[0-9A-Z]{5}$/).optional(),
|
|
75
|
+
severity: z.enum(["ERROR", "FATAL", "PANIC", "WARNING", "NOTICE", "DEBUG", "INFO", "LOG"]).optional(),
|
|
76
|
+
message: z.string().optional() });
|
|
77
|
+
function parse(schema, value, operation, code, uncertain = false) {
|
|
78
|
+
// Zod/JSON may throw on cyclic values too; those exceptions must not cross the boundary.
|
|
79
|
+
try {
|
|
80
|
+
const parsed = schema.safeParse(value);
|
|
81
|
+
if (parsed.success)
|
|
82
|
+
return parsed.data;
|
|
83
|
+
}
|
|
84
|
+
catch { /* Report the same fixed reason for non-JSON input. */ }
|
|
85
|
+
throw new PlanerClientError(code, operation, uncertain);
|
|
86
|
+
}
|
|
87
|
+
function sdkFailure(error, operation, mutation) {
|
|
88
|
+
if (error instanceof PlanerClientError)
|
|
89
|
+
return new PlanerClientError(error.code, operation, mutation, { plannerCode: error.plannerCode, requestId: error.requestId });
|
|
90
|
+
// Numeric transport codes only; the SDK's message embeds untrusted HTTP response bodies.
|
|
91
|
+
if (error instanceof StreamableHTTPError) {
|
|
92
|
+
const code = error.code === 401 ? "UNAUTHORIZED" : error.code === 403 ? "FORBIDDEN"
|
|
93
|
+
: error.code === 429 ? "RATE_LIMITED" : "HTTP_ERROR";
|
|
94
|
+
return new PlanerClientError(code, operation, mutation);
|
|
95
|
+
}
|
|
96
|
+
if (error instanceof McpError)
|
|
97
|
+
return new PlanerClientError(error.code === ErrorCode.RequestTimeout ? "TIMEOUT" : "RPC_ERROR", operation, mutation);
|
|
98
|
+
return new PlanerClientError("TRANSPORT_ERROR", operation, mutation);
|
|
99
|
+
}
|
|
100
|
+
function toolFailure(value, operation, mutation) {
|
|
101
|
+
// Tool diagnostics can follow a committed write whose COMMIT acknowledgement was lost.
|
|
102
|
+
const update = updateFailure.safeParse(value);
|
|
103
|
+
if (update.success)
|
|
104
|
+
return new PlanerClientError("TOOL_ERROR", operation, mutation, { plannerCode: update.data.code, requestId: update.data.requestId });
|
|
105
|
+
const large = tooLargeFailure.safeParse(value);
|
|
106
|
+
if (large.success)
|
|
107
|
+
return new PlanerClientError("TOOL_ERROR", operation, mutation, { plannerCode: large.data.code });
|
|
108
|
+
const diagnostic = runFailure.safeParse(value);
|
|
109
|
+
return new PlanerClientError("TOOL_ERROR", operation, mutation, diagnostic.success
|
|
110
|
+
? { plannerCode: diagnostic.data.code, requestId: diagnostic.data.requestId } : undefined);
|
|
111
|
+
}
|
|
112
|
+
function taskProjection(raw, selected, operation) {
|
|
113
|
+
const object = parse(z.record(z.string(), z.unknown()), raw, operation, "INVALID_RESPONSE");
|
|
114
|
+
if (object.detailsReadError !== undefined && object.detailsReadError !== null)
|
|
115
|
+
throw new PlanerClientError("DETAILS_READ_ERROR", operation);
|
|
116
|
+
const task = parse(taskSchema, object, operation, "INVALID_RESPONSE");
|
|
117
|
+
if (!selected.length)
|
|
118
|
+
return task;
|
|
119
|
+
const details = parse(jsonObject.nullable(), object.details, operation, "INVALID_RESPONSE");
|
|
120
|
+
return { ...task, details: details === null ? null : Object.fromEntries(Object.entries(details).filter(([key]) => selected.includes(key))) };
|
|
121
|
+
}
|
|
122
|
+
/** Existing MCP operations only. No auto-connect, retry, CAS emulation or runtime cutover. */
|
|
123
|
+
export class PlanerClient {
|
|
124
|
+
#client = new Client({ name: PACKAGE_NAME, version: PACKAGE_VERSION });
|
|
125
|
+
#transport;
|
|
126
|
+
#deadlineMs;
|
|
127
|
+
#state = "new";
|
|
128
|
+
#connecting;
|
|
129
|
+
constructor(config) {
|
|
130
|
+
const parsed = parse(z.strictObject({ origin: z.string().optional(), endpoint: z.string().optional(),
|
|
131
|
+
token: z.string().regex(KEY_PATTERN), fetch: z.custom(value => typeof value === "function").optional(),
|
|
132
|
+
deadlineMs: z.number().int().min(1).max(2_147_483_647).default(15_000), }).refine(value => (value.origin === undefined) !== (value.endpoint === undefined)), config, "connect", "INVALID_CONFIG");
|
|
133
|
+
let endpoint;
|
|
134
|
+
try {
|
|
135
|
+
const origin = parsed.origin === undefined ? undefined : new URL(parsed.origin);
|
|
136
|
+
endpoint = new URL(parsed.endpoint ?? mcpUrl(origin.origin));
|
|
137
|
+
if (!["http:", "https:"].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.search || endpoint.hash
|
|
138
|
+
|| (origin && origin.href !== `${origin.origin}/`))
|
|
139
|
+
throw new Error("Invalid endpoint");
|
|
140
|
+
}
|
|
141
|
+
catch {
|
|
142
|
+
throw new PlanerClientError("INVALID_CONFIG", "connect");
|
|
143
|
+
}
|
|
144
|
+
this.#deadlineMs = parsed.deadlineMs;
|
|
145
|
+
const fetcher = parsed.fetch ?? globalThis.fetch;
|
|
146
|
+
let initializeObserved = false;
|
|
147
|
+
this.#transport = new StreamableHTTPClientTransport(endpoint, {
|
|
148
|
+
requestInit: { headers: { authorization: `Bearer ${parsed.token}` }, redirect: "error" },
|
|
149
|
+
// Deliberately no authProvider: 401/403 must never trigger automatic POST replay.
|
|
150
|
+
reconnectionOptions: { maxRetries: 0, initialReconnectionDelay: 1000, maxReconnectionDelay: 30_000, reconnectionDelayGrowFactor: 1.5 },
|
|
151
|
+
fetch: async (url, init) => {
|
|
152
|
+
const signal = AbortSignal.any([...(init?.signal ? [init.signal] : []), AbortSignal.timeout(this.#deadlineMs)]);
|
|
153
|
+
// SDK connect always sends initialize as its first POST (no authProvider/sessionId).
|
|
154
|
+
const initialize = !initializeObserved && init?.method === "POST";
|
|
155
|
+
if (initialize)
|
|
156
|
+
initializeObserved = true;
|
|
157
|
+
let response;
|
|
158
|
+
try {
|
|
159
|
+
response = await fetcher(url, { ...init, signal });
|
|
160
|
+
}
|
|
161
|
+
catch {
|
|
162
|
+
throw new PlanerClientError(signal.aborted ? "TIMEOUT" : "TRANSPORT_ERROR", "connect");
|
|
163
|
+
}
|
|
164
|
+
if (initialize && response.ok) {
|
|
165
|
+
try {
|
|
166
|
+
assertCompatible(response.headers.get(CONTRACT_VERSION_HEADER));
|
|
167
|
+
}
|
|
168
|
+
catch {
|
|
169
|
+
try {
|
|
170
|
+
await response.body?.cancel();
|
|
171
|
+
}
|
|
172
|
+
catch { /* The version failure still owns this result. */ }
|
|
173
|
+
throw new PlanerClientError("CONTRACT_VERSION", "connect");
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
return response;
|
|
177
|
+
},
|
|
178
|
+
});
|
|
179
|
+
// SDK errors are handled at each awaited call. Do not log untrusted asynchronous stream errors.
|
|
180
|
+
this.#client.onerror = () => { };
|
|
181
|
+
}
|
|
182
|
+
async connect() {
|
|
183
|
+
if (this.#state === "closed")
|
|
184
|
+
throw new PlanerClientError("CLOSED", "connect");
|
|
185
|
+
if (this.#state === "connected")
|
|
186
|
+
return;
|
|
187
|
+
if (this.#connecting)
|
|
188
|
+
return this.#connecting;
|
|
189
|
+
this.#state = "connecting";
|
|
190
|
+
this.#connecting = (async () => {
|
|
191
|
+
try {
|
|
192
|
+
await this.#client.connect(this.#transport, { timeout: this.#deadlineMs, maxTotalTimeout: this.#deadlineMs });
|
|
193
|
+
if (this.#state === "closed")
|
|
194
|
+
throw new PlanerClientError("CLOSED", "connect");
|
|
195
|
+
this.#state = "connected";
|
|
196
|
+
}
|
|
197
|
+
catch (error) {
|
|
198
|
+
this.#state = "closed";
|
|
199
|
+
try {
|
|
200
|
+
await this.#client.close();
|
|
201
|
+
}
|
|
202
|
+
catch { /* Preserve the sanitized connection failure. */ }
|
|
203
|
+
throw sdkFailure(error, "connect", false);
|
|
204
|
+
}
|
|
205
|
+
})();
|
|
206
|
+
return this.#connecting;
|
|
207
|
+
}
|
|
208
|
+
async close() {
|
|
209
|
+
this.#state = "closed";
|
|
210
|
+
try {
|
|
211
|
+
await this.#client.close();
|
|
212
|
+
}
|
|
213
|
+
catch (error) {
|
|
214
|
+
throw sdkFailure(error, "close", false);
|
|
215
|
+
}
|
|
216
|
+
}
|
|
217
|
+
async #call(operation, args, mutation = false) {
|
|
218
|
+
if (this.#state !== "connected")
|
|
219
|
+
throw new PlanerClientError("NOT_CONNECTED", operation);
|
|
220
|
+
let result;
|
|
221
|
+
try {
|
|
222
|
+
// callTool's declaration also includes the legacy toolResult envelope. Narrow with the SDK schema.
|
|
223
|
+
result = CallToolResultSchema.parse(await this.#client.callTool({ name: operation, arguments: args }, undefined, { timeout: this.#deadlineMs, maxTotalTimeout: this.#deadlineMs }));
|
|
224
|
+
}
|
|
225
|
+
catch (error) {
|
|
226
|
+
throw sdkFailure(error, operation, mutation);
|
|
227
|
+
}
|
|
228
|
+
let value;
|
|
229
|
+
try {
|
|
230
|
+
if (result.content.length !== 1 || result.content[0]?.type !== "text")
|
|
231
|
+
throw new Error("Invalid tool content");
|
|
232
|
+
value = JSON.parse(result.content[0].text);
|
|
233
|
+
}
|
|
234
|
+
catch {
|
|
235
|
+
throw new PlanerClientError(result.isError ? "TOOL_ERROR" : "INVALID_RESPONSE", operation, mutation);
|
|
236
|
+
}
|
|
237
|
+
return { value, isError: result.isError === true };
|
|
238
|
+
}
|
|
239
|
+
async #value(operation, args, mutation = false) {
|
|
240
|
+
const result = await this.#call(operation, args, mutation);
|
|
241
|
+
if (result.isError)
|
|
242
|
+
throw toolFailure(result.value, operation, mutation);
|
|
243
|
+
return result.value;
|
|
244
|
+
}
|
|
245
|
+
async listProjects(args = {}) {
|
|
246
|
+
const input = parse(z.strictObject({}), args, "list_projects", "INVALID_ARGUMENT");
|
|
247
|
+
return parse(z.array(projectSchema), await this.#value("list_projects", input), "list_projects", "INVALID_RESPONSE");
|
|
248
|
+
}
|
|
249
|
+
async listTracks(args) {
|
|
250
|
+
const input = parse(z.strictObject({ projectId: uuid }), args, "list_tracks", "INVALID_ARGUMENT");
|
|
251
|
+
return parse(z.array(trackSchema), await this.#value("list_tracks", input), "list_tracks", "INVALID_RESPONSE");
|
|
252
|
+
}
|
|
253
|
+
async createTrack(args) {
|
|
254
|
+
const input = parse(createTrackInput, args, "create_track", "INVALID_ARGUMENT");
|
|
255
|
+
const track = parse(trackSchema, await this.#value("create_track", input, true), "create_track", "INVALID_RESPONSE", true);
|
|
256
|
+
if (track.projectId !== input.projectId)
|
|
257
|
+
throw new PlanerClientError("INVALID_RESPONSE", "create_track", true);
|
|
258
|
+
return track;
|
|
259
|
+
}
|
|
260
|
+
async createTask(args) {
|
|
261
|
+
const input = parse(createTaskInput, args, "create_task", "INVALID_ARGUMENT");
|
|
262
|
+
const echo = parse(createTaskSchema, await this.#value("create_task", input, true), "create_task", "INVALID_RESPONSE", true);
|
|
263
|
+
if (echo.trackId !== input.trackId)
|
|
264
|
+
throw new PlanerClientError("INVALID_RESPONSE", "create_task", true);
|
|
265
|
+
return echo;
|
|
266
|
+
}
|
|
267
|
+
async listTasks(args) {
|
|
268
|
+
const input = parse(listInput, args, "list_tasks", "INVALID_ARGUMENT");
|
|
269
|
+
const rows = parse(z.array(z.unknown()), await this.#value("list_tasks", { ...input, full: true }), "list_tasks", "INVALID_RESPONSE");
|
|
270
|
+
return rows.map(raw => ({ ...taskProjection(raw, input.detailsKeys, "list_tasks"),
|
|
271
|
+
depsReady: parse(z.object({ depsReady: z.boolean() }), raw, "list_tasks", "INVALID_RESPONSE").depsReady }));
|
|
272
|
+
}
|
|
273
|
+
async getTask(args) {
|
|
274
|
+
const input = parse(getInput, args, "get_task", "INVALID_ARGUMENT");
|
|
275
|
+
const value = await this.#value("get_task", input);
|
|
276
|
+
if (value === null)
|
|
277
|
+
return null;
|
|
278
|
+
const task = taskProjection(value, input.include, "get_task");
|
|
279
|
+
if (task.id !== input.id)
|
|
280
|
+
throw new PlanerClientError("INVALID_RESPONSE", "get_task");
|
|
281
|
+
const detailsIndex = parse(z.object({ availableDetailsKeys: keys.nullable().optional() }), value, "get_task", "INVALID_RESPONSE");
|
|
282
|
+
return { ...task, ...detailsIndex };
|
|
283
|
+
}
|
|
284
|
+
async reserveTask(args) {
|
|
285
|
+
const input = parse(reserveInput, args, "reserve_task", "INVALID_ARGUMENT");
|
|
286
|
+
const echo = parse(reservationSchema, await this.#value("reserve_task", input, true), "reserve_task", "INVALID_RESPONSE", true);
|
|
287
|
+
if (echo.id !== input.id)
|
|
288
|
+
throw new PlanerClientError("INVALID_RESPONSE", "reserve_task", true);
|
|
289
|
+
return echo;
|
|
290
|
+
}
|
|
291
|
+
/** Server snapshot of an in_review card; does not confirm enforced policy or code/model provenance.
|
|
292
|
+
* Rejects malformed/mismatched responses with INVALID_RESPONSE, uncertain=false. */
|
|
293
|
+
async getReviewSnapshot(args) {
|
|
294
|
+
const input = parse(reviewSnapshotInput, args, "get_review_snapshot", "INVALID_ARGUMENT");
|
|
295
|
+
const snapshot = parse(reviewSnapshotSchema, await this.#value("get_review_snapshot", input), "get_review_snapshot", "INVALID_RESPONSE");
|
|
296
|
+
if (snapshot.cardId !== input.id)
|
|
297
|
+
throw new PlanerClientError("INVALID_RESPONSE", "get_review_snapshot");
|
|
298
|
+
return snapshot;
|
|
299
|
+
}
|
|
300
|
+
/** Server owns policy, authenticated actor and atomic receipt/delivered write. providerDeclared is
|
|
301
|
+
* only a declaration, not proof of model execution. No retry, update_task fallback or snapshot refresh.
|
|
302
|
+
* Strict input: matching id/cardId, UUIDs, lowercase 64-hex snapshot, trimmed 1–200 character declaration.
|
|
303
|
+
* Local validation fails with INVALID_ARGUMENT/uncertain=false; failures after sending are uncertain.
|
|
304
|
+
* After an uncertain write, caller must explicitly getTask({id, include:['review_receipt']}) and decide. */
|
|
305
|
+
async acceptReview(args) {
|
|
306
|
+
const input = parse(acceptReviewInput, args, "accept_review", "INVALID_ARGUMENT");
|
|
307
|
+
const echo = parse(echoSchema, await this.#value("accept_review", input, true), "accept_review", "INVALID_RESPONSE", true);
|
|
308
|
+
if (echo.id !== input.id || echo.status !== "delivered")
|
|
309
|
+
throw new PlanerClientError("INVALID_RESPONSE", "accept_review", true);
|
|
310
|
+
return echo;
|
|
311
|
+
}
|
|
312
|
+
/** For draft promotion, pass {status:'ready', expected:{status:'draft'}}. Server owns CAS/permissions. */
|
|
313
|
+
async updateTask(args) {
|
|
314
|
+
const input = parse(updateInput, args, "update_task", "INVALID_ARGUMENT");
|
|
315
|
+
const echo = parse(echoSchema, await this.#value("update_task", input, true), "update_task", "INVALID_RESPONSE", true);
|
|
316
|
+
if (echo.id !== input.id)
|
|
317
|
+
throw new PlanerClientError("INVALID_RESPONSE", "update_task", true);
|
|
318
|
+
return echo;
|
|
319
|
+
}
|
|
320
|
+
/** Flat server merge; null is literal. No deep merge, chunking, append guard or implicit retry. */
|
|
321
|
+
async appendDetail(args) {
|
|
322
|
+
const input = parse(appendInput, args, "append_detail", "INVALID_ARGUMENT");
|
|
323
|
+
const write = parse(appendSchema, await this.#value("append_detail", input, true), "append_detail", "INVALID_RESPONSE", true);
|
|
324
|
+
const included = Object.keys(input.patch);
|
|
325
|
+
if (write.id !== input.id || write.appendedKeys.length !== included.length || !included.every(key => write.appendedKeys.includes(key))) {
|
|
326
|
+
throw new PlanerClientError("INVALID_RESPONSE", "append_detail", true);
|
|
327
|
+
}
|
|
328
|
+
try {
|
|
329
|
+
return { write, readback: { ok: true, task: await this.getTask({ id: input.id, include: included }) } };
|
|
330
|
+
}
|
|
331
|
+
catch (error) {
|
|
332
|
+
return { write, readback: { ok: false, error: sdkFailure(error, "get_task", false) } };
|
|
333
|
+
}
|
|
334
|
+
}
|
|
335
|
+
/** full/owner_validator authority stays on the server. Non-CLOSED outcomes retain isError. */
|
|
336
|
+
async closeDecisionMatter(args) {
|
|
337
|
+
const input = parse(closeInput, args, "close_decision_matter", "INVALID_ARGUMENT");
|
|
338
|
+
const result = await this.#call("close_decision_matter", input, true);
|
|
339
|
+
const parsed = closeSchema.safeParse(result.value);
|
|
340
|
+
if (!parsed.success) {
|
|
341
|
+
if (result.isError)
|
|
342
|
+
throw toolFailure(result.value, "close_decision_matter", true);
|
|
343
|
+
throw new PlanerClientError("INVALID_RESPONSE", "close_decision_matter", true);
|
|
344
|
+
}
|
|
345
|
+
const { outcome, cardId, matterId } = parsed.data;
|
|
346
|
+
if (cardId !== input.id || matterId !== input.matterId || result.isError !== (outcome !== "CLOSED")) {
|
|
347
|
+
throw new PlanerClientError("INVALID_RESPONSE", "close_decision_matter", true);
|
|
348
|
+
}
|
|
349
|
+
return { outcome, cardId, matterId, isError: result.isError };
|
|
350
|
+
}
|
|
351
|
+
}
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
export type HostRestartWorkerState = "alive" | "terminal" | "dead" | "unknown";
|
|
2
|
+
export type HostRestartDecision = {
|
|
3
|
+
action: "no_restart_evidence";
|
|
4
|
+
} | {
|
|
5
|
+
action: "wait";
|
|
6
|
+
phase: "restart-alive";
|
|
7
|
+
} | {
|
|
8
|
+
action: "wait_unknown";
|
|
9
|
+
phase: "restart-unknown";
|
|
10
|
+
} | {
|
|
11
|
+
action: "terminal_passthrough";
|
|
12
|
+
} | {
|
|
13
|
+
action: "recover_to_review";
|
|
14
|
+
phase: "restart-recovered";
|
|
15
|
+
recovery_reason: "dead-after-host-restart";
|
|
16
|
+
worker_finished: false;
|
|
17
|
+
} | {
|
|
18
|
+
action: "retry";
|
|
19
|
+
phase: "restart-retry";
|
|
20
|
+
} | {
|
|
21
|
+
action: "hold_unknown";
|
|
22
|
+
phase: "restart-hold-unknown";
|
|
23
|
+
reason: string;
|
|
24
|
+
};
|
|
25
|
+
/** Both timestamps valid ISO and host boot strictly after worker start. */
|
|
26
|
+
export declare function hasHostRestartEvidence(hostBootAt: string | null | undefined, activeStartedAt: string): boolean;
|
|
27
|
+
/**
|
|
28
|
+
* Normalize helper status under optional restart evidence.
|
|
29
|
+
* Reksio (b): queued|running with hostBootAt > startedAt ⇒ dead (pre-boot process cannot be alive).
|
|
30
|
+
*/
|
|
31
|
+
export declare function classifyRestartWorkerState(helperStatus: string, hostBootAt: string | null | undefined, activeStartedAt: string): HostRestartWorkerState;
|
|
32
|
+
/** Decision matrix once workerState is known. Used by tick and by the unknown→dead counterfactual test. */
|
|
33
|
+
export declare function decideHostRestartFromState(input: {
|
|
34
|
+
restartEvidence: boolean;
|
|
35
|
+
workerState: HostRestartWorkerState;
|
|
36
|
+
commitsAhead: number | null;
|
|
37
|
+
hasReviewableDiff: boolean | null;
|
|
38
|
+
worktreeClean: boolean | null;
|
|
39
|
+
}): HostRestartDecision;
|
|
40
|
+
export declare function decideHostRestart(input: {
|
|
41
|
+
hostBootAt: string | null | undefined;
|
|
42
|
+
activeStartedAt: string;
|
|
43
|
+
helperStatus: string;
|
|
44
|
+
commitsAhead: number | null;
|
|
45
|
+
hasReviewableDiff: boolean | null;
|
|
46
|
+
worktreeClean: boolean | null;
|
|
47
|
+
}): HostRestartDecision;
|