@workpowers/speckle 0.9.0 → 0.9.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/README.md +26 -0
- package/dist/headers.d.ts +14 -1
- package/dist/headers.js +13 -2
- package/dist/index.js +3 -0
- package/dist/workflow-client.js +2 -2
- package/dist/workflow-contract.d.ts +40 -2
- package/dist/workflow-contract.js +16 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -54,6 +54,32 @@ and it cannot tell the server anything about your checkout — so freshness stay
|
|
|
54
54
|
`unknown` no matter what is installed on disk. `speckle-mcp doctor` prints which
|
|
55
55
|
directory it searched.
|
|
56
56
|
|
|
57
|
+
### Cloud sessions (Claude Code on the web)
|
|
58
|
+
|
|
59
|
+
A cloud session starts in a fresh container that has no user-scope
|
|
60
|
+
registration, and it loads MCP servers **before** any SessionStart hook runs, so
|
|
61
|
+
a hook that writes `.mcp.json` comes too late. Register the router from the
|
|
62
|
+
cloud environment's **Setup script** instead (claude.ai → Settings →
|
|
63
|
+
Environments), which runs before Claude Code launches:
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
#!/bin/bash
|
|
67
|
+
# Speckle MCP for cloud sessions. Claude Code loads MCP servers before SessionStart hooks run, so the repo hook comes too late; this runs before launch.
|
|
68
|
+
root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
|
|
69
|
+
printf '%s\n' '{"generated-by":"session-start-hook","mcpServers":{"speckle":{"command":"npx","args":["-y","@workpowers/speckle"],"env":{"SPECKLE_MCP_BASE_URL":"https://speckle.workpowers.ai","SPECKLE_MCP_KEY":"${SPECKLE_MCP_KEY}"}}}}' > "$root/.mcp.json"
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
The same environment needs:
|
|
73
|
+
|
|
74
|
+
- the environment variable `SPECKLE_MCP_KEY=lsk_...` (from `/account#mcp`);
|
|
75
|
+
- network access to `speckle.workpowers.ai` (package registries stay allowed, so
|
|
76
|
+
`npx` can fetch the router).
|
|
77
|
+
|
|
78
|
+
The key is written into `.mcp.json` as the literal `${SPECKLE_MCP_KEY}`, which
|
|
79
|
+
Claude Code expands when it reads the file, so the key itself never reaches
|
|
80
|
+
disk. The file is gitignored; the `generated-by` marker is kept from the retired
|
|
81
|
+
SessionStart hook so the file is recognisably machine-written.
|
|
82
|
+
|
|
57
83
|
## Point a repo at a project
|
|
58
84
|
|
|
59
85
|
Commit a `.speckle` marker at the repo root:
|
package/dist/headers.d.ts
CHANGED
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
*/
|
|
14
14
|
import type { ResolvedWorkspace } from "./workspace.js";
|
|
15
15
|
export declare const ROUTER_CLIENT_NAME = "@workpowers/speckle";
|
|
16
|
-
export declare const ROUTER_CLIENT_VERSION = "0.9.
|
|
16
|
+
export declare const ROUTER_CLIENT_VERSION = "0.9.2";
|
|
17
17
|
/**
|
|
18
18
|
* The MCP client the router serves, as it named itself at initialize
|
|
19
19
|
* (`claude-code/2.1.0`), so the server can say which door a person's quoted
|
|
@@ -22,6 +22,15 @@ export declare const ROUTER_CLIENT_VERSION = "0.9.0";
|
|
|
22
22
|
* after that carries it.
|
|
23
23
|
*/
|
|
24
24
|
export declare const MCP_CLIENT_HEADER = "X-Speckle-Mcp-Client";
|
|
25
|
+
/**
|
|
26
|
+
* One agent session, as the router process that serves it (I-8763). The
|
|
27
|
+
* stdio router is one process per agent session, and the HTTP server keeps
|
|
28
|
+
* no session of its own, so the router mints a random id at start and sends
|
|
29
|
+
* it on every request. The server writes it on each call-log row, which is
|
|
30
|
+
* what lets it say whether a session read the spec before its first write.
|
|
31
|
+
* Telemetry only: never an identity and never auth.
|
|
32
|
+
*/
|
|
33
|
+
export declare const AGENT_SESSION_HEADER = "X-Speckle-Agent-Session";
|
|
25
34
|
export interface RouterRequestHeaders {
|
|
26
35
|
Authorization: string;
|
|
27
36
|
"X-Speckle-Client": string;
|
|
@@ -31,6 +40,7 @@ export interface RouterRequestHeaders {
|
|
|
31
40
|
"X-Speckle-Project-Slug"?: string;
|
|
32
41
|
"X-Speckle-Repo-Remote"?: string;
|
|
33
42
|
"X-Speckle-Mcp-Client"?: string;
|
|
43
|
+
"X-Speckle-Agent-Session"?: string;
|
|
34
44
|
}
|
|
35
45
|
export declare function buildRouterHeaders(args: {
|
|
36
46
|
apiKey: string;
|
|
@@ -43,5 +53,8 @@ export declare function buildRouterHeaders(args: {
|
|
|
43
53
|
* deliberately absent because there is no marker to attest.
|
|
44
54
|
*/
|
|
45
55
|
fallbackProjectId?: number;
|
|
56
|
+
/** The agent session this router process serves (I-8763); the stdio router
|
|
57
|
+
* passes one random id per process, the one-shot commands pass none. */
|
|
58
|
+
agentSessionId?: string;
|
|
46
59
|
}): RouterRequestHeaders;
|
|
47
60
|
//# sourceMappingURL=headers.d.ts.map
|
package/dist/headers.js
CHANGED
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
* the server then exposes a project-agnostic discovery toolset.
|
|
13
13
|
*/
|
|
14
14
|
export const ROUTER_CLIENT_NAME = "@workpowers/speckle";
|
|
15
|
-
export const ROUTER_CLIENT_VERSION = "0.9.
|
|
15
|
+
export const ROUTER_CLIENT_VERSION = "0.9.2";
|
|
16
16
|
/**
|
|
17
17
|
* The MCP client the router serves, as it named itself at initialize
|
|
18
18
|
* (`claude-code/2.1.0`), so the server can say which door a person's quoted
|
|
@@ -21,12 +21,23 @@ export const ROUTER_CLIENT_VERSION = "0.9.0";
|
|
|
21
21
|
* after that carries it.
|
|
22
22
|
*/
|
|
23
23
|
export const MCP_CLIENT_HEADER = "X-Speckle-Mcp-Client";
|
|
24
|
+
/**
|
|
25
|
+
* One agent session, as the router process that serves it (I-8763). The
|
|
26
|
+
* stdio router is one process per agent session, and the HTTP server keeps
|
|
27
|
+
* no session of its own, so the router mints a random id at start and sends
|
|
28
|
+
* it on every request. The server writes it on each call-log row, which is
|
|
29
|
+
* what lets it say whether a session read the spec before its first write.
|
|
30
|
+
* Telemetry only: never an identity and never auth.
|
|
31
|
+
*/
|
|
32
|
+
export const AGENT_SESSION_HEADER = "X-Speckle-Agent-Session";
|
|
24
33
|
export function buildRouterHeaders(args) {
|
|
25
|
-
const { apiKey, workspace, fallbackProjectId } = args;
|
|
34
|
+
const { apiKey, workspace, fallbackProjectId, agentSessionId } = args;
|
|
26
35
|
const headers = {
|
|
27
36
|
Authorization: `Bearer ${apiKey}`,
|
|
28
37
|
"X-Speckle-Client": `${ROUTER_CLIENT_NAME}/${ROUTER_CLIENT_VERSION}`,
|
|
29
38
|
};
|
|
39
|
+
if (agentSessionId)
|
|
40
|
+
headers[AGENT_SESSION_HEADER] = agentSessionId;
|
|
30
41
|
if (!workspace) {
|
|
31
42
|
if (fallbackProjectId !== undefined) {
|
|
32
43
|
headers["X-Speckle-Project-Id"] = String(fallbackProjectId);
|
package/dist/index.js
CHANGED
|
@@ -35,6 +35,7 @@ import { buildRouterHeaders, MCP_CLIENT_HEADER, ROUTER_CLIENT_NAME, ROUTER_CLIEN
|
|
|
35
35
|
import { mirrorServerOptions, wireProxyHandlers } from "./proxy.js";
|
|
36
36
|
import { SpeckleRouterError } from "./errors.js";
|
|
37
37
|
import path from "node:path";
|
|
38
|
+
import { randomUUID } from "node:crypto";
|
|
38
39
|
import { createWorkflowClient } from "./workflow-client.js";
|
|
39
40
|
export async function startRouter() {
|
|
40
41
|
const config = loadRouterConfig();
|
|
@@ -65,6 +66,8 @@ export async function startRouter() {
|
|
|
65
66
|
apiKey: config.apiKey,
|
|
66
67
|
workspace,
|
|
67
68
|
fallbackProjectId: workspace ? undefined : config.fallbackProjectId,
|
|
69
|
+
// This process serves one agent session; every call it forwards says so (I-8763).
|
|
70
|
+
agentSessionId: randomUUID(),
|
|
68
71
|
});
|
|
69
72
|
const upstream = new Client({ name: ROUTER_CLIENT_NAME, version: ROUTER_CLIENT_VERSION }, { capabilities: {} });
|
|
70
73
|
const httpTransport = new StreamableHTTPClientTransport(new URL(`${host.hostUrl}/mcp`), {
|
package/dist/workflow-client.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
/** Per-router-session metadata. Re-read checkout evidence on every call; never equate notice delivery with adoption. */
|
|
2
2
|
import { randomUUID } from "node:crypto";
|
|
3
3
|
import { z } from "zod";
|
|
4
|
-
import { WORKFLOW_META, publicationSchema } from "./workflow-contract.js";
|
|
4
|
+
import { WORKFLOW_META, guidanceRevision, publicationSchema } from "./workflow-contract.js";
|
|
5
5
|
import { observeWorkflowFiles, cachedWorkflowFallback } from "./workflow-files.js";
|
|
6
6
|
const responseMeta = z.object({
|
|
7
7
|
notice_id: z.string(), notice_delivered: z.boolean(), fetched_revision: z.string().optional(),
|
|
@@ -29,7 +29,7 @@ export function createWorkflowClient(options) {
|
|
|
29
29
|
if (isWorkflowFetch(params) && !r.isError) {
|
|
30
30
|
const publication = publicationSchema.safeParse(r.structuredContent);
|
|
31
31
|
if (publication.success)
|
|
32
|
-
fetchedRevision = publication.data
|
|
32
|
+
fetchedRevision = guidanceRevision(publication.data);
|
|
33
33
|
}
|
|
34
34
|
},
|
|
35
35
|
fallback(params) {
|
|
@@ -47,6 +47,27 @@ export declare const publicationSchema: z.ZodObject<{
|
|
|
47
47
|
content: string;
|
|
48
48
|
summary: string;
|
|
49
49
|
}>;
|
|
50
|
+
rules: z.ZodOptional<z.ZodEffects<z.ZodObject<{
|
|
51
|
+
revision: z.ZodString;
|
|
52
|
+
content: z.ZodString;
|
|
53
|
+
summary: z.ZodString;
|
|
54
|
+
}, "strip", z.ZodTypeAny, {
|
|
55
|
+
revision: string;
|
|
56
|
+
content: string;
|
|
57
|
+
summary: string;
|
|
58
|
+
}, {
|
|
59
|
+
revision: string;
|
|
60
|
+
content: string;
|
|
61
|
+
summary: string;
|
|
62
|
+
}>, {
|
|
63
|
+
revision: string;
|
|
64
|
+
content: string;
|
|
65
|
+
summary: string;
|
|
66
|
+
}, {
|
|
67
|
+
revision: string;
|
|
68
|
+
content: string;
|
|
69
|
+
summary: string;
|
|
70
|
+
}>>;
|
|
50
71
|
bootstrap: z.ZodEffects<z.ZodObject<{
|
|
51
72
|
revision: z.ZodString;
|
|
52
73
|
content: z.ZodString;
|
|
@@ -80,6 +101,11 @@ export declare const publicationSchema: z.ZodObject<{
|
|
|
80
101
|
content: string;
|
|
81
102
|
summary: string;
|
|
82
103
|
};
|
|
104
|
+
rules?: {
|
|
105
|
+
revision: string;
|
|
106
|
+
content: string;
|
|
107
|
+
summary: string;
|
|
108
|
+
} | undefined;
|
|
83
109
|
}, {
|
|
84
110
|
protocol_version: 1;
|
|
85
111
|
planning: {
|
|
@@ -92,8 +118,19 @@ export declare const publicationSchema: z.ZodObject<{
|
|
|
92
118
|
content: string;
|
|
93
119
|
summary: string;
|
|
94
120
|
};
|
|
121
|
+
rules?: {
|
|
122
|
+
revision: string;
|
|
123
|
+
content: string;
|
|
124
|
+
summary: string;
|
|
125
|
+
} | undefined;
|
|
95
126
|
}>;
|
|
96
127
|
export type WorkflowPublication = z.infer<typeof publicationSchema>;
|
|
128
|
+
/**
|
|
129
|
+
* The revision a session has fetched: the planning revision, or, once the
|
|
130
|
+
* answer carries rules, one hash over both, so a changed rule raises the
|
|
131
|
+
* same notice a changed step does (I-8746).
|
|
132
|
+
*/
|
|
133
|
+
export declare const guidanceRevision: (publication: WorkflowPublication) => string;
|
|
97
134
|
declare const observation: z.ZodObject<{
|
|
98
135
|
state: z.ZodEnum<["observed", "missing", "unreadable"]>;
|
|
99
136
|
hash: z.ZodOptional<z.ZodString>;
|
|
@@ -290,8 +327,6 @@ export declare function compareObservation(observed: FileObservation | undefined
|
|
|
290
327
|
export declare function workflowStatus(publication: WorkflowPublication, context?: WorkflowContext): {
|
|
291
328
|
notice_id: string;
|
|
292
329
|
notify: boolean;
|
|
293
|
-
protocol_version: 1;
|
|
294
|
-
planning_revision: string;
|
|
295
330
|
bootstrap_revision: string;
|
|
296
331
|
session: string;
|
|
297
332
|
checkout: {
|
|
@@ -301,6 +336,9 @@ export declare function workflowStatus(publication: WorkflowPublication, context
|
|
|
301
336
|
bootstrap: string;
|
|
302
337
|
planning_cache: string;
|
|
303
338
|
};
|
|
339
|
+
rules_revision?: string | undefined;
|
|
340
|
+
protocol_version: 1;
|
|
341
|
+
planning_revision: string;
|
|
304
342
|
};
|
|
305
343
|
export {};
|
|
306
344
|
//# sourceMappingURL=workflow-contract.d.ts.map
|
|
@@ -15,8 +15,19 @@ export const artifactSchema = z.object({
|
|
|
15
15
|
export const publicationSchema = z.object({
|
|
16
16
|
protocol_version: z.literal(1),
|
|
17
17
|
planning: artifactSchema,
|
|
18
|
+
// Rules for every project (I-8746): standing rules beside the steps, with
|
|
19
|
+
// their own revision. Optional so a client reading an older server parses.
|
|
20
|
+
rules: artifactSchema.optional(),
|
|
18
21
|
bootstrap: artifactSchema,
|
|
19
22
|
});
|
|
23
|
+
/**
|
|
24
|
+
* The revision a session has fetched: the planning revision, or, once the
|
|
25
|
+
* answer carries rules, one hash over both, so a changed rule raises the
|
|
26
|
+
* same notice a changed step does (I-8746).
|
|
27
|
+
*/
|
|
28
|
+
export const guidanceRevision = (publication) => publication.rules
|
|
29
|
+
? hashContent(`${publication.planning.revision}\n${publication.rules.revision}`)
|
|
30
|
+
: publication.planning.revision;
|
|
20
31
|
const observation = z.object({
|
|
21
32
|
state: z.enum(["observed", "missing", "unreadable"]),
|
|
22
33
|
hash: hash.optional(),
|
|
@@ -66,8 +77,12 @@ export function workflowStatus(publication, context = {}) {
|
|
|
66
77
|
const status = {
|
|
67
78
|
protocol_version: 1,
|
|
68
79
|
planning_revision: publication.planning.revision,
|
|
80
|
+
...(publication.rules ? { rules_revision: publication.rules.revision } : {}),
|
|
69
81
|
bootstrap_revision: publication.bootstrap.revision,
|
|
70
|
-
|
|
82
|
+
// A router published before I-8746 echoes the planning revision alone; it
|
|
83
|
+
// keeps planning-only freshness rather than an endless notice.
|
|
84
|
+
session: context.fetched_revision === guidanceRevision(publication) ||
|
|
85
|
+
context.fetched_revision === publication.planning.revision ? "fetched" :
|
|
71
86
|
context.fetched_revision ? "outdated" : "unknown",
|
|
72
87
|
checkout: {
|
|
73
88
|
workspace_id: context.workspace_id ?? null,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@workpowers/speckle",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.2",
|
|
4
4
|
"description": "Local MCP router for Speckle — resolves project context from a committed .speckle marker and forwards calls to the remote Speckle MCP endpoint.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|