@workpowers/speckle 0.9.0 → 0.9.1

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.1";
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
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.1";
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
@@ -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.1",
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",