@abseed/spectra-agent-tools 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Luke Pezet
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,6 @@
+Spectra
+Copyright 2026 Luke Pezet
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this project except in compliance with the License. You may obtain a copy of the
+License in the LICENSE file, or at http://www.apache.org/licenses/LICENSE-2.0

package/dist/agents.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Who is in the channel — the two agents, as data.
+ *
+ * Two agents with deliberately different reach. `@spec` has domain tools and no filesystem at all, so
+ * it cannot bypass the changesets-only rule. `@coder` has real file access, but rooted at its project
+ * and with the glossary path explicitly denied — it implements what the glossary says and cannot
+ * quietly rewrite the glossary to match what it built.
+ *
+ * WHY this lives in `@abseed/spectra-agent-tools` and not the server: the definitions are the single source
+ * of who `@spec` and `@coder` are, and a runtime fetches them from the coordinator rather than
+ * carrying its own copy (the copy an attacker in the box could edit). Both coordinators — the open
+ * server and the hosted Worker — must serve the *same* definitions, so they live beside the tools.
+ * The only host-specific parts are the two filesystem paths the definitions reference (the glossary
+ * dir and @coder's working dir); those are passed in, so this stays free of node builtins.
+ */
+import type { AuthorKind, ProjectInfo } from '@abseed/spectra-core';
+export type AgentName = Extract<AuthorKind, 'spec' | 'coder'>;
+export interface AgentDefinition {
+    name: AgentName;
+    /** Shown in the composer and on message chips. */
+    label: string;
+    description: string;
+    systemPrompt: string;
+    cwd: string;
+    /** Built-in tools. Empty disables the filesystem entirely. */
+    builtins: string[];
+    /**
+     * Built-ins that run without asking. Anything in `builtins` but not here goes through the approval
+     * card — and note the SDK's rule: a tool named bare in `allowedTools` never reaches the permission
+     * callback, so listing a write here silently disables its card.
+     */
+    autoApprove: string[];
+    /** Domain tools this agent may call, by short name. */
+    domainTools: string[];
+    disallowedTools?: string[];
+}
+/** The filesystem paths the definitions reference — supplied by the host, never assumed. */
+export interface AgentPaths {
+    /** The glossary directory: @spec's cwd, and the path @coder is forbidden to write. */
+    specsDir: string;
+    /** @coder's working directory — the project it implements into. */
+    appDir: string;
+}
+/**
+ * The two agent definitions, built for a given project so their shared prompt names the real
+ * glossary, and for a given host so their paths are the real ones. Constructed in the coordinator's
+ * composition root from `store.projectInfo()`.
+ */
+export declare function buildAgents(project: ProjectInfo, paths: AgentPaths): Record<AgentName, AgentDefinition>;
+export declare const AGENT_NAMES: AgentName[];

package/dist/agents.js

@@ -0,0 +1,140 @@
+// The project's name and domain are threaded in, not hardcoded — they come from the SpecStore, so the
+// same coordinator serves whatever glossary it is pointed at.
+const sharedPrompt = (project) => `You are one of two agents in a channel with a human, working on ${project.name}: a shared glossary that a human and an AI coder both work from, describing ${project.domain}. The glossary lives in specs/terms as JSON — Terms with a spec, a parent, and typed attributes.
+
+The other agent is addressed as @spec or @coder. You cannot message them; only the human can. If work belongs to the other one, say so and let the human hand it over.
+
+You can see the whole channel, including messages addressed to the other agent. Read them for context; act only on what is addressed to you.
+
+Be concise and concrete. Cite term names, question ids and changeset ids. Prefer quoting spec text over paraphrasing it.
+
+Lead with the conclusion. The first sentence of your final message must be a single plain sentence saying what happened or what the answer is, and the detail goes after it. Two things read that sentence and nothing else: the folded view of a finished run, and a screen reader speaking it aloud. So keep it free of file paths, code and formatting — ids like q-009 or completeTask are fine because they are short and mean something, but "app/src/domain/domain.test.ts now passes" is not a sentence anyone can hear. "The tests pass and q-009 is still open" is.
+
+That sentence is not a summary of your whole reply and should not try to be. If the work had one outcome, say it. If it had two, say the one that decides what happens next.`;
+/**
+ * The two agent definitions, built for a given project so their shared prompt names the real
+ * glossary, and for a given host so their paths are the real ones. Constructed in the coordinator's
+ * composition root from `store.projectInfo()`.
+ */
+export function buildAgents(project, paths) {
+    const SHARED = sharedPrompt(project);
+    const { specsDir: SPECS_DIR, appDir: APP_DIR } = paths;
+    // The object below keeps its original indentation — its systemPrompt template literals are
+    // multi-line, so re-indenting would corrupt the prompt text.
+    return {
+        spec: {
+            name: 'spec',
+            label: 'spec',
+            description: 'Reads and edits the glossary. Proposes changesets, raises questions.',
+            cwd: SPECS_DIR,
+            // No filesystem at all: everything it can reach goes through the domain tools, which
+            // is what keeps the human write path changesets-only.
+            builtins: [],
+            autoApprove: [],
+            domainTools: [
+                'read_glossary',
+                'read_questions',
+                'read_changesets',
+                'read_expectations',
+                'analyze_pending',
+                'search_transcripts',
+                'raise_question',
+                'raise_expectation',
+                'propose_changeset',
+            ],
+            systemPrompt: `${SHARED}
+
+You own the glossary. You cannot edit terms directly and must not describe doing so as though you could.
+
+Route a request to one of four places, and say which:
+1. The change is clear and no product decision is left — propose a changeset.
+2. It turns on a choice only the human can make — raise a question, and do not settle the fork by proposing one side of it.
+3. The specs already say what a thing is, but nobody has said what should happen in some situation — raise an expectation. This is the common case for anything noticed while using the app rather than reading the glossary.
+4. It needs no glossary change at all — say so plainly. The glossary describes the domain, not the app that renders it, so presentation, wording and display are implementation work for @coder. Saying "that is app work, not a spec change" is a real answer, not a refusal to help.
+
+A question is for a decision a human must make, not for an observation. If it cannot be phrased as something someone answers, do not raise it.
+
+Questions and expectations are not the same thing and the difference is who decides. A question asks; an expectation asserts. If you know what should happen, record an expectation. If it turns on a decision nobody has made, ask — writing an expectation instead would settle a product question by stating it as fact.
+
+An expectation marked contested disagrees with a term's spec and was recorded anyway. It covers nothing until that is settled, and settling it is a decision for the human — so raise a question naming both sides, quoting the expectation and the spec sentence it clashes with. Do not propose a changeset that quietly makes the spec match the expectation, and do not suggest retiring the expectation as though it were obviously wrong: it is usually a change somebody wants and nobody has proposed yet.
+
+When asked what is untested, under-specified, or what to think about next, call read_expectations with coverage. It reports which entity/action pairs nothing has been said about. Do not work that out by reading terms: the pairs that matter are the ones two hops apart, which is exactly what nobody spots by eye.
+
+When asked what to work on first, call analyze_pending and answer from what it returns. Do not reason about conflicts by reading ops yourself — order-dependent breakage is easy to get wrong by eye and the tool replays it through the real engine.`,
+        },
+        coder: {
+            name: 'coder',
+            label: 'coder',
+            description: 'Implements applied changesets in app/. Cannot edit specs.',
+            cwd: APP_DIR,
+            builtins: ['Read', 'Glob', 'Grep', 'Edit', 'Write', 'Bash'],
+            // Reading is free; changing a file or running a command is not. Edit, Write and Bash
+            // are deliberately absent, which is what routes them through the approval card.
+            //
+            // With one caveat, found by testing rather than by reading: for Bash the SDK classifies
+            // the command itself and lets ones it judges read-only through without a card. `pwd &&
+            // ls` ran unprompted; `touch app/probe-file` raised a card and was blocked. So the card
+            // covers commands that change things, which is the useful guarantee — but it is not
+            // "every command", and the prompts must not claim otherwise.
+            autoApprove: ['Read', 'Glob', 'Grep'],
+            // Reads the glossary through the same read-only tools @spec uses, so it works from the
+            // specs without being able to touch them. It can raise a question — an implementation
+            // pass hitting something the specs do not settle is where most questions come from.
+            domainTools: [
+                'read_glossary',
+                'read_questions',
+                'read_changesets',
+                // Reads what must hold and can add to it, but has no tool to retire one — the move that
+                // turns a red check green without touching code stays a human act.
+                'read_expectations',
+                'raise_expectation',
+                'search_transcripts',
+                'raise_question',
+                'mark_implemented',
+                // How the drift check gets its half of the inputs back. app/ cannot see specs/ from
+                // inside the sandbox, so the glossary arrives as a file @coder writes and commits.
+                'export_specs',
+            ],
+            /**
+             * Path rules for the file tools, plus a short denylist of shell commands.
+             *
+             * Be clear about what this is worth: Bash escapes every path restriction here — `cd`
+             * goes anywhere, redirection writes anywhere. The approval card is the actual boundary,
+             * and these patterns are a speed bump for the obviously destructive cases, not a
+             * sandbox. A sandbox is the next step, and this is the reason for it.
+             */
+            disallowedTools: [
+                `Edit(//${SPECS_DIR}/**)`,
+                `Write(//${SPECS_DIR}/**)`,
+                'Bash(rm -rf *)',
+                'Bash(git commit *)',
+                'Bash(git push *)',
+                'Bash(git reset *)',
+                'Bash(git checkout *)',
+            ],
+            systemPrompt: `${SHARED}
+
+You own app/. You implement what the glossary already says; you do not decide what it should say.
+
+Working directory is app/. You can read, search, edit and create files there. You cannot write to specs/ — if the specs are wrong, incomplete, or say two contradictory things, raise a question rather than working around it or changing the code to something the specs do not describe.
+
+How to run an implementation pass:
+0. export_specs, and write what it returns verbatim to specs.snapshot.json in your working directory. That file is the contract the drift check reads, and it is how the code can be checked against the specs without being able to see them. Refresh it first, so \`git diff specs.snapshot.json\` shows you exactly which terms moved since the code was last written — including spec rewrites, which the markers cannot show you.
+1. read_changesets and read_glossary to see what landed and what the terms now say. Do this even after refreshing the snapshot: the snapshot carries hashes, not spec text, so it tells you which terms moved and never what they now say. Knowing a hash changed is not knowing the requirement.
+2. Find the files whose "// implements:" marker names the affected terms. That marker is the link from a term to the code responsible for it — keep it accurate, and add the term to a marker when you make a file responsible for it.
+3. Change the code to match. Quote the spec text you are implementing in the file, as the existing files do. Every edit is shown to the human for approval before it happens, so make one focused change at a time and say what it is for — a diff nobody can follow gets declined.
+4. Update the tests, including any the changeset committed to under "tests". Call read_expectations for what must hold, and name the expectation id in the test that proves it — \`it('e-014: deleteProject refuses while a live RecurringTask remains', ...)\`. That id is what links a statement in the specs to the test standing behind it, and it has to survive being read years later.
+5. Never write code to satisfy a contested expectation. It disagrees with a term's spec, so making it true would make the specs false, and you cannot change those. Report it and move on — the human settles which side gives.
+6. If implementing turned up a situation the specs name but never settle the outcome of, call raise_expectation. Do not fix it silently in code and do not retire an existing expectation your code just failed — you have no tool for the second, deliberately. An expectation that has become wrong is a human decision; say so and let the human retire it.
+7. Run \`npm test\` and \`npm run typecheck\` in your working directory to check your work, and fix what they report.
+8. Call mark_implemented with the changeset id. It is refused unless your stored snapshot is at the current specs version — the same way a push is refused when the remote has moved. If that happens, the specs changed while you were working: refresh the snapshot, read what actually changed, make sure the code still matches, then call it again. There is no override, and asking for one is not the answer.
+
+You have a shell. Every command that changes anything is shown to the human before it runs; commands the SDK judges read-only run without asking. Use it to check your work — running tests, typechecking, searching. Prefer the project's own scripts over ad-hoc commands, and say what a command is for. Do not commit, push, or otherwise touch git: the human owns the history, and those commands are refused anyway.
+
+If an ambiguity is cheap to get wrong, pick a reading, say which you picked and why, and move on. If getting it wrong would waste the work, stop and raise a question instead.`,
+        },
+    };
+}
+// Static: the roster is fixed by construction, not derived from a built instance, so it needs no
+// ProjectInfo and callers can validate an agent name without building the definitions.
+export const AGENT_NAMES = ['spec', 'coder'];

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './tools.js';
+export * from './agents.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './tools.js';
+export * from './agents.js';

package/dist/tools.d.ts

@@ -0,0 +1,73 @@
+/**
+ * The agent's tool surface — the pure, transport-agnostic half.
+ *
+ * These are domain tools, not file tools, and that is the whole point. The human write path is
+ * changesets-only; if the agent had `Write` on the glossary it could edit a term directly and the
+ * discipline would rest on the system prompt asking it not to. Here it rests on there being no such
+ * tool. The agent physically cannot bypass review.
+ *
+ * WHY this is its own package, not `@abseed/spectra-core`: these schemas are consumed by the agent SDK,
+ * which peer-requires zod 4, while core is zod 3. So the tool definitions live here (zod 4, no node
+ * builtins, no SDK dependency) where both the open server and the hosted coordinator can import them
+ * — the server registers them in-process and over HTTP, the Worker over its fetch-native MCP.
+ *
+ * Only the *pure* tools live here: reads, plus `propose_changeset` and `raise_question` (whose write
+ * logic is in core). The three that touch the host — `raise_expectation` (a model-backed check),
+ * `mark_implemented` and `export_specs` (a filesystem snapshot) — stay in the server and are composed
+ * on top of these (see the server's `toolsFor`).
+ *
+ * The tool objects are plain `SdkMcpToolDefinition`-shaped records (see {@link defineTool}); the agent
+ * SDK's `tool()` helper is only a typed constructor for that same shape, so we reproduce it here
+ * rather than depend on the SDK.
+ */
+import { z } from 'zod';
+import type { Author, SpecStore, TranscriptStore } from '@abseed/spectra-core';
+/** MCP tools answer with content blocks; every tool here returns one JSON or text block. */
+export interface CallResult {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+}
+/** Read-only/behaviour hints passed through to the MCP registration, mirroring the SDK's shape. */
+export type ToolAnnotations = {
+    readOnlyHint?: boolean;
+} & Record<string, unknown>;
+/**
+ * A tool as both consumers expect it: the agent SDK's `SdkMcpToolDefinition` (for the in-process
+ * server) and the MCP SDK's `registerTool` (for the HTTP/fetch server) both read exactly these
+ * fields, so this one shape serves both.
+ */
+export interface ToolDef {
+    name: string;
+    description: string;
+    inputSchema: z.ZodRawShape;
+    handler: (args: Record<string, unknown>, extra: unknown) => Promise<CallResult>;
+    annotations?: ToolAnnotations;
+}
+/**
+ * The plain-object equivalent of the SDK's `tool()` — a constructor, no runtime behaviour. Exported
+ * so the server can define its host-coupled tools (raise_expectation, mark_implemented, export_specs)
+ * in the same shape and compose them with these.
+ */
+export declare function defineTool<S extends z.ZodRawShape>(name: string, description: string, inputSchema: S, handler: (args: z.infer<z.ZodObject<S>>, extra: unknown) => Promise<CallResult>, annotations?: ToolAnnotations): ToolDef;
+/** Every tool answers with one content block — JSON when structured, text otherwise. */
+export declare function say(value: unknown): CallResult;
+/**
+ * The pure tools, constructed for a given store/transcripts/author. No version stamping here — that
+ * is applied by {@link withVersion}, so the server (filesystem snapshot) and the cloud (its own
+ * scheme) can each supply how the current version is read.
+ */
+export declare function pureTools(store: SpecStore, transcripts: TranscriptStore, author: Author): ToolDef[];
+/**
+ * Stamp every tool's result with the current specs version.
+ *
+ * A `stale: true` flag would be one process's opinion; a version is a fact both sides hold and
+ * compare (the same reason git prints `abc123..def456`). `versionOf` is injected so each host reads
+ * it its own way — the server from its filesystem snapshot, the cloud from its store.
+ */
+export declare function withVersion(tools: ToolDef[], versionOf: () => Promise<string>): ToolDef[];
+/** Filter a tool list to the names an agent may call. Never taken from the tool arguments. */
+export declare function pick(tools: ToolDef[], names: readonly string[]): ToolDef[];
+/** The `mcp__blueprints__`-qualified names, for the SDK's allowedTools. */
+export declare function qualified(names: readonly string[]): string[];

package/dist/tools.js

@@ -0,0 +1,313 @@
+/**
+ * The agent's tool surface — the pure, transport-agnostic half.
+ *
+ * These are domain tools, not file tools, and that is the whole point. The human write path is
+ * changesets-only; if the agent had `Write` on the glossary it could edit a term directly and the
+ * discipline would rest on the system prompt asking it not to. Here it rests on there being no such
+ * tool. The agent physically cannot bypass review.
+ *
+ * WHY this is its own package, not `@abseed/spectra-core`: these schemas are consumed by the agent SDK,
+ * which peer-requires zod 4, while core is zod 3. So the tool definitions live here (zod 4, no node
+ * builtins, no SDK dependency) where both the open server and the hosted coordinator can import them
+ * — the server registers them in-process and over HTTP, the Worker over its fetch-native MCP.
+ *
+ * Only the *pure* tools live here: reads, plus `propose_changeset` and `raise_question` (whose write
+ * logic is in core). The three that touch the host — `raise_expectation` (a model-backed check),
+ * `mark_implemented` and `export_specs` (a filesystem snapshot) — stay in the server and are composed
+ * on top of these (see the server's `toolsFor`).
+ *
+ * The tool objects are plain `SdkMcpToolDefinition`-shaped records (see {@link defineTool}); the agent
+ * SDK's `tool()` helper is only a typed constructor for that same shape, so we reproduce it here
+ * rather than depend on the SDK.
+ */
+import { z } from 'zod';
+import { analyzePending, computeBacklinks, computeCoverage, proposeChangeset, raiseQuestion, summarizeOp } from '@abseed/spectra-core';
+/**
+ * The plain-object equivalent of the SDK's `tool()` — a constructor, no runtime behaviour. Exported
+ * so the server can define its host-coupled tools (raise_expectation, mark_implemented, export_specs)
+ * in the same shape and compose them with these.
+ */
+export function defineTool(name, description, inputSchema, handler, annotations) {
+    return {
+        name,
+        description,
+        inputSchema,
+        handler: handler,
+        ...(annotations ? { annotations } : {}),
+    };
+}
+/**
+ * An op as the *tool* accepts it: one flat shape with an enum tag and optional fields, rather than
+ * the discriminated union the engine uses. Nested inside `options[] → proposal → ops[]`, a
+ * `z.discriminatedUnion` defeats the SDK's JSON-Schema conversion and the whole MCP server silently
+ * fails to register. Nothing is lost: both write paths run the real schema over the result before
+ * writing, so a malformed op is rejected there with a readable message rather than landing on disk.
+ */
+const attributeInput = z.object({
+    name: z.string(),
+    valueType: z.string().describe('string | number | boolean | date | ref:<TermName>, each with an optional [] suffix'),
+    default: z.unknown().optional(),
+    optional: z.boolean().optional(),
+});
+const opInput = z.object({
+    op: z.enum(['add_entity', 'remove_entity', 'add_attribute', 'remove_attribute', 'modify_spec']),
+    term: z.string().describe('The term this op targets'),
+    termType: z.enum(['entity', 'event', 'function', 'attribute-type']).optional().describe('add_entity only; defaults to entity'),
+    parent: z.string().nullable().optional().describe('add_entity only'),
+    spec: z.string().optional().describe('Required for add_entity and modify_spec'),
+    tags: z.array(z.string()).optional(),
+    attributes: z.array(attributeInput).optional().describe('add_entity only'),
+    attribute: z
+        .union([attributeInput, z.string()])
+        .optional()
+        .describe('add_attribute takes the attribute object; remove_attribute takes just its name as a string'),
+});
+const proposalInput = z.object({
+    summary: z.string(),
+    ops: z.array(opInput),
+    tests: z.array(z.string()).describe('Plain-language behaviours this change commits to'),
+});
+/** Every tool answers with one content block — JSON when structured, text otherwise. */
+export function say(value) {
+    return {
+        content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }],
+    };
+}
+/** A term plus the relationships that make it make sense — the useful unit, not the file. */
+function describeTerm(terms, name) {
+    const term = terms.find((candidate) => candidate.name === name);
+    if (!term)
+        return null;
+    const backlinks = computeBacklinks(terms);
+    return {
+        ...term,
+        children: backlinks.children[name] ?? [],
+        referencedBy: (backlinks.byTarget[name] ?? []).map((reference) => ({ from: reference.from, via: reference.via })),
+    };
+}
+/** Everything pending, flattened into comparable op-lists for the conflict analysis. */
+function pendingItems(changesets, questions) {
+    const items = changesets.map((changeset) => ({
+        id: changeset.id,
+        kind: 'changeset',
+        label: changeset.summary,
+        ops: changeset.ops,
+    }));
+    for (const question of questions) {
+        if (question.answer)
+            continue;
+        for (const option of question.options) {
+            if (!option.proposal)
+                continue;
+            items.push({
+                id: `${question.id}:${option.label}`,
+                kind: 'question-option',
+                label: `${question.id} — ${option.label}`,
+                ops: option.proposal.ops,
+            });
+        }
+    }
+    return items;
+}
+/**
+ * The pure tools, constructed for a given store/transcripts/author. No version stamping here — that
+ * is applied by {@link withVersion}, so the server (filesystem snapshot) and the cloud (its own
+ * scheme) can each supply how the current version is read.
+ */
+export function pureTools(store, transcripts, author) {
+    const readGlossary = defineTool('read_glossary', 'Read the spec glossary. Omit `term` for every term in summary form; supply one to get its full spec, attributes, subtypes and everything that references it.', { term: z.string().optional().describe('A single term name, e.g. "Task"') }, async (args) => {
+        const { terms, problems } = await store.readTerms();
+        if (args.term) {
+            const described = describeTerm(terms, args.term);
+            return say(described ?? { error: `No term named "${args.term}".`, known: terms.map((term) => term.name) });
+        }
+        return say({
+            terms: terms.map((term) => ({
+                name: term.name,
+                type: term.type,
+                spec: term.spec,
+                parent: term.parent,
+                attributes: term.attributes.map((attribute) => `${attribute.name}: ${attribute.valueType}`),
+            })),
+            problems,
+        });
+    }, { readOnlyHint: true });
+    const readQuestions = defineTool('read_questions', 'Read questions raised against the glossary — what it does not settle, and what has been decided. Answered questions are the record of why the specs say what they say.', { status: z.enum(['open', 'answered', 'all']).optional().describe('Defaults to "all"') }, async (args) => {
+        const { questions, problems } = await store.readQuestions();
+        const status = args.status ?? 'all';
+        const filtered = questions.filter((question) => status === 'all' ? true : status === 'open' ? !question.answer : Boolean(question.answer));
+        return say({
+            questions: filtered.map((question) => ({
+                id: question.id,
+                asks: question.asks,
+                because: question.because,
+                raisedBy: question.raisedBy,
+                options: question.options.map((option) => ({
+                    label: option.label,
+                    detail: option.detail,
+                    ops: option.proposal?.ops.map(summarizeOp) ?? null,
+                })),
+                answer: question.answer,
+            })),
+            problems,
+        });
+    }, { readOnlyHint: true });
+    const readChangesets = defineTool('read_changesets', 'Read changesets: `outstanding` are applied but not yet implemented — the work, and where to find the id mark_implemented wants. `pending` are proposed and awaiting human review; do not implement those, they may still be rejected or changed. `implemented` is history.', {}, async () => {
+        const { changesets, applied, problems } = await store.readChangesets();
+        const describe = (changeset) => ({
+            id: changeset.id,
+            summary: changeset.summary,
+            fromQuestion: changeset.fromQuestion,
+            appliedAt: changeset.appliedAt,
+            ops: changeset.ops.map(summarizeOp),
+            tests: changeset.tests,
+        });
+        return say({
+            outstanding: applied.filter((changeset) => !changeset.implementedAt).map(describe),
+            pending: changesets.map(describe),
+            implemented: applied
+                .filter((changeset) => changeset.implementedAt)
+                .map((changeset) => ({ id: changeset.id, summary: changeset.summary, implementedAt: changeset.implementedAt })),
+            problems,
+        });
+    }, { readOnlyHint: true });
+    const readExpectations = defineTool('read_expectations', 'Read the expectations — what someone should be able to expect, stated outside the prose of the specs. Functional ones become tests over the domain; non-functional ones describe a running build. Pass `coverage` to get which entity/action pairs nothing has been said about yet, nearest first: that list is the work queue for what the glossary has named but nobody has thought through.', {
+        coverage: z.boolean().optional().describe('Return the pair-coverage report instead of the expectation list'),
+        term: z.string().optional().describe('Only expectations naming this term'),
+    }, async (args) => {
+        const [{ terms }, { expectations, retired, problems }] = await Promise.all([store.readTerms(), store.readExpectations()]);
+        if (args.coverage) {
+            const report = computeCoverage(terms, expectations);
+            return say({
+                ...report,
+                note: 'Coverage means an expectation exists naming both ends of the pair — not that the behaviour is correct. distance 1 is an action naming the entity directly; 2 is reached through the entity graph, which is where the interactions nobody thought about tend to sit.',
+            });
+        }
+        const wanted = (list) => (args.term ? list.filter((expectation) => expectation.terms.includes(args.term)) : list);
+        const live = wanted(expectations);
+        const contested = live.filter((expectation) => expectation.contested.length > 0);
+        return say({
+            expectations: live,
+            ...(contested.length > 0
+                ? {
+                    warning: `${contested.map((entry) => entry.id).join(', ')} disagree with the specs and were recorded anyway. Do not write code to satisfy a contested expectation and do not change the specs to match it — which side gives is a decision only the human can make. Say what you found and leave it.`,
+                }
+                : {}),
+            retired: wanted(retired).map((expectation) => ({
+                id: expectation.id,
+                expect: expectation.expect,
+                supersededBy: expectation.supersededBy,
+                retiredBecause: expectation.retiredBecause,
+            })),
+            problems,
+        });
+    }, { readOnlyHint: true });
+    const analyzePendingTool = defineTool('analyze_pending', 'Work out what to tackle first. Replays every pending changeset and unanswered question option through the changeset engine, alone and in pairs, and reports which ones break which — including cases where order is what matters. Use this before recommending where to start; do not reason it out by hand.', {}, async () => {
+        const [{ terms }, { changesets }, { questions }] = await Promise.all([store.readTerms(), store.readChangesets(), store.readQuestions()]);
+        const items = pendingItems(changesets, questions);
+        const report = analyzePending(terms, items);
+        return say({
+            ...report,
+            note: 'A conflict listed as {first, second} means applying `first` before `second` causes the diagnostics shown. If the reverse pair is absent, that order is safe.',
+        });
+    }, { readOnlyHint: true });
+    const searchTranscripts = defineTool('search_transcripts', 'Search earlier conversations in this workspace for a word or phrase. Use it before asking the human to repeat context they may already have given.', {
+        query: z.string().describe('Substring to look for, case-insensitive'),
+        limit: z.number().int().min(1).max(50).optional(),
+    }, async (args) => {
+        const hits = await transcripts.search(args.query, args.limit ?? 20);
+        return say(hits.map((hit) => ({ session: hit.title, sessionId: hit.sessionId, role: hit.kind, at: hit.createdAt, text: hit.text })));
+    }, { readOnlyHint: true });
+    const raiseQuestionTool = defineTool('raise_question', [
+        'Raise a question against the glossary. Use this when the specs do not settle something a human must decide — never to record an observation.',
+        'If it cannot be phrased as a question someone answers, it does not belong here.',
+        '`because` must quote the spec text in conflict. "This was awkward to implement" is not grounds to change a spec; "these two spec sentences cannot both hold" is.',
+        'The number of options is the answer shape: one means approve-or-decline, several means a genuine choice (do not signal a favourite by ordering), none means only the human can write the spec text.',
+        'Do not use this to propose a change you are confident about and could simply describe — that is what a changeset is for.',
+    ].join(' '), {
+        asks: z.string().describe('The question itself, answerable as written'),
+        because: z.string().describe('Why it is being asked, quoting the conflicting spec text verbatim'),
+        pass: z.string().describe('What was being done when it came up, e.g. "implementation" or "review"'),
+        file: z.string().optional().describe('Source file where it surfaced, if any'),
+        terms: z.array(z.string()).describe('Glossary terms the question is about'),
+        options: z
+            .array(z.object({
+            label: z.string(),
+            detail: z.string().optional().describe('The tradeoff in plain language, including what this choice costs'),
+            proposal: proposalInput.nullable().optional().describe('The changeset this option would raise. Null when it changes no specs.'),
+        }))
+            .describe('Candidate answers; may be empty when only the human can write the spec'),
+    }, async (args) => {
+        const outcome = await raiseQuestion(store, {
+            asks: args.asks,
+            because: args.because,
+            pass: args.pass,
+            file: args.file,
+            terms: args.terms,
+            options: args.options,
+        }, author);
+        return say(outcome.ok
+            ? { raised: outcome.id, file: `specs/questions/${outcome.file}`, awaiting: 'a human answer' }
+            : { error: outcome.error });
+    });
+    const proposeChangesetTool = defineTool('propose_changeset', [
+        'Propose an edit to the glossary. Use this when the change is clear and there is no product decision left to make — a missing term, a spec that says two things, a name that does not match what it describes.',
+        'It lands in the pending queue and changes nothing until a human reviews and applies it, so it is safe to propose; it is not safe to guess.',
+        'If the change turns on a choice only the human can make, raise a question instead. Do not settle a fork by proposing one side of it — a changeset that quietly picked a default is far harder to review than a question that names the options.',
+        'If the request needs no glossary change at all — presentation, wording in the UI, how something is displayed or implemented — say so and do not propose anything. The glossary describes the domain, not the app that renders it.',
+        'Say in your reply what you did not decide. A proposal that names its own open ends is worth more than one that reads as finished.',
+    ].join(' '), {
+        summary: z.string().describe('One line: what this change does'),
+        ops: z.array(opInput).describe('The edits, applied in order'),
+        tests: z.array(z.string()).describe('Plain-language behaviours this change commits to — what a reviewer should expect to hold afterwards'),
+        fromQuestion: z.string().optional().describe('Id of an already-answered question this follows from, if any'),
+    }, async (args) => {
+        const outcome = await proposeChangeset(store, {
+            summary: args.summary,
+            ops: args.ops,
+            tests: args.tests,
+            ...(args.fromQuestion ? { fromQuestion: args.fromQuestion } : {}),
+        }, author);
+        return say(outcome.ok
+            ? { proposed: outcome.id, file: `specs/changesets/${outcome.file}`, awaiting: 'human review — nothing has changed in the glossary yet' }
+            : { error: outcome.error });
+    });
+    return [
+        readGlossary,
+        readQuestions,
+        readChangesets,
+        readExpectations,
+        analyzePendingTool,
+        searchTranscripts,
+        raiseQuestionTool,
+        proposeChangesetTool,
+    ];
+}
+/**
+ * Stamp every tool's result with the current specs version.
+ *
+ * A `stale: true` flag would be one process's opinion; a version is a fact both sides hold and
+ * compare (the same reason git prints `abc123..def456`). `versionOf` is injected so each host reads
+ * it its own way — the server from its filesystem snapshot, the cloud from its store.
+ */
+export function withVersion(tools, versionOf) {
+    return tools.map((tool) => ({
+        ...tool,
+        handler: async (args, extra) => {
+            const result = await tool.handler(args, extra);
+            return {
+                ...result,
+                content: [...result.content, { type: 'text', text: JSON.stringify({ specsVersion: await versionOf() }) }],
+            };
+        },
+    }));
+}
+/** Filter a tool list to the names an agent may call. Never taken from the tool arguments. */
+export function pick(tools, names) {
+    const wanted = new Set(names);
+    return tools.filter((tool) => wanted.has(tool.name));
+}
+/** The `mcp__blueprints__`-qualified names, for the SDK's allowedTools. */
+export function qualified(names) {
+    return names.map((name) => `mcp__blueprints__${name}`);
+}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@abseed/spectra-agent-tools",
+  "version": "0.1.0",
+  "description": "Spectra's agent tool definitions and the @spec/@coder agent roster — Worker-safe, pure.",
+  "license": "Apache-2.0",
+  "author": "Luke Pezet",
+  "homepage": "https://github.com/lpezet/spectra/tree/main/packages/agent-tools",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lpezet/spectra.git",
+    "directory": "packages/agent-tools"
+  },
+  "keywords": [
+    "spectra",
+    "spec-driven",
+    "agent",
+    "mcp",
+    "tools"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "dependencies": {
+    "@abseed/spectra-core": "^0.1.0",
+    "zod": "^4.4.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}