@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 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.0";
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.0";
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`), {
@@ -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.planning.revision;
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
- session: context.fetched_revision === publication.planning.revision ? "fetched" :
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.0",
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",