@mnmal-ai/cortext-opencode 1.0.0-alpha.7 → 1.0.0-alpha.8

package/README.md

@@ -18,7 +18,7 @@ OpenCode 1.x compat).
      "$schema": "https://opencode.ai/config.json",
      "plugins": [
        {
-         "package": "@mnmal-ai/cortext-opencode",
+         "package": "@mnmal-ai/cortext-opencode@next",
          "options": {
            "kid": "synoptic-opencode@YourHost",
            "key": "/home/you/.config/substrate/keys/synoptic-opencode.key"
@@ -28,7 +28,7 @@ OpenCode 1.x compat).
    }
    ```
 
-   The plain string form (`"plugins": ["@mnmal-ai/cortext-opencode"]`) also
+   The plain string form (`"plugins": ["@mnmal-ai/cortext-opencode@next"]`) also
    works — identity then comes from the env pair. **Keep exactly one entry
    per package**: as of opencode v2.0.24 the `plugins`
    arrays concatenate across global + project config and loads dedupe only
@@ -40,7 +40,7 @@ OpenCode 1.x compat).
    public on npmjs.com, as is the `@mnmal-ai/substrate` dep; no token needed.
 
 2. MCP server — merge into the same `opencode.json` (see
-   `commands/substrate-setup.md` Step 4 for the full procedure). **The MCP server
+   `skills/substrate-setup/SKILL.md` Step 4 for the full procedure). **The MCP server
    must sign as the same identity as the plugin**: the plugin shows
    mail for its `options.kid`, and only that kid may ack it. With
    `options.kid`/`options.key`, give the MCP `environment` the same kid and
@@ -53,7 +53,7 @@ OpenCode 1.x compat).
        "servers": {
          "substrate": {
            "type": "local",
-           "command": ["npx", "-y", "@mnmal-ai/substrate", "mcp"],
+           "command": ["npx", "-y", "@mnmal-ai/substrate@next", "mcp"],
            "codemode": false,
            "environment": {
              "SUBSTRATE_URL": "https://substrate.example.com:3100",
@@ -77,10 +77,18 @@ OpenCode 1.x compat).
    version. An older hand-copied `.opencode/substrate-conventions.md` is named in
    the session context as stale; delete it and its `"instructions"` entry.
 
-4. Restart opencode (config loads once at startup). Or run `/substrate-setup`
-   (copy `commands/substrate-setup.md` to `.opencode/commands/`) for the guided
-   version of all of the above plus capability probing, AgentRule seeding,
-   identity provisioning, and the first anchor.
+4. Restart opencode (config loads once at startup), then install the
+   skills. OpenCode loads no skills from a plugin package, so copy them to the
+   user skills directory, and again after each plugin update:
+
+   ```bash
+   PKG=$(ls -d ~/.cache/opencode/npm/@mnmal-ai/cortext-opencode@next/*/node_modules/@mnmal-ai/cortext-opencode | sort | tail -1)
+   mkdir -p ~/.config/opencode/skills && cp -R "$PKG/skills/." ~/.config/opencode/skills/
+   ```
+
+   The `substrate-setup` skill is the guided version of all of the above plus
+   capability probing, AgentRule seeding, identity provisioning, and the
+   first anchor.
 
 ## Environment
 
@@ -105,8 +113,9 @@ OpenCode 1.x compat).
 | `Stop` inbox check (blocks once) | V2: a `session.execution.succeeded` event with unread mail queues one synthetic message carrying the same reason, with `resume: true`. Each message id nudges once. `SYNOPTIC_INBOX_STOP_CHECK=off` disables it |
 | Mid-turn push (`inbox-bridge`) | V2: the watcher runs in-process; new mail is steered into every busy session, allowlisted urgent mail preempts the most recently prompted session, and idle wake is opt-in. While the watcher is live the per-prompt summary is skipped; the end-of-turn nudge stays |
 | `skills/{council,todos}` | `skills/{council,todos}` — byte-identical pointer bodies (`test/skills-sync.test.ts` enforces) |
+| `skills/substrate-run` | `skills/substrate-run` — shared steps 1–5, own binary/identity and permission steps (`test/skills-sync.test.ts` enforces) |
 | `fragments/substrate-conventions.md` | `instructions/substrate-conventions.md` — shared body, own marker (`test/instructions-sync.test.ts` enforces) |
-| `/substrate-setup` skill | `commands/substrate-setup.md` — opencode paths + MCP dialect |
+| `/substrate-setup` skill | `skills/substrate-setup` — opencode paths + MCP dialect |
 | SessionStart `compact` re-run | `compaction` session hook: drops the cache (next dispatch rebuilds) + leaves a pointer in the summary |
 | Fragment-drift watchdog | **Deferred** — the check reads the `.claude/` install path; see `src/plugin.ts` header |
 

package/dist/plugin.js

@@ -69,14 +69,22 @@ function mint(kid, key, ns, capabilities, aud) {
 		exp
 	};
 }
-/** The origin a token for `url` names as its `aud`; throws rather than mint a token without one. */
+const LOOPBACK = /^(localhost|127\.\d{1,3}\.\d{1,3}\.\d{1,3}|\[::1\])$/;
+/**
+* The origin a token for `url` names as its `aud`. Throws rather than mint a
+* token without one, or one bound for plain http to a non-loopback host, where
+* the network can read it. Same rule as substrate-client's `tokenAudience`.
+*/
 function audienceOf(url) {
 	const raw = typeof url === "object" && url !== null && "url" in url ? url.url : url;
+	let parsed;
 	try {
-		return new URL(String(raw)).origin;
+		parsed = new URL(String(raw));
 	} catch {
 		throw new Error(`cannot mint an agent token without an audience: '${raw}' is not a URL`);
 	}
+	if (parsed.protocol === "https:" || parsed.protocol === "http:" && LOOPBACK.test(parsed.hostname)) return parsed.origin;
+	throw new Error(`refusing to send an agent token to ${parsed.origin}: use https, or plain http only to a loopback host`);
 }
 function misconfigured(detail) {
 	return {
@@ -160,6 +168,7 @@ function makeSignedFetch(getAuthHeader, fetchImpl = fetch) {
 		if (header === null) return fetchImpl(url, init);
 		return fetchImpl(url, {
 			...init,
+			redirect: "error",
 			headers: {
 				...init.headers,
 				authorization: header

package/instructions/substrate-conventions.md

@@ -1,4 +1,4 @@
-<!-- substrate-conventions vsynoptic-1.0.0-alpha.7+9d0bf8e1 — opencode skin; plugin-owned, do not edit. Edit your own AGENTS.md instead. Body is shared with the Claude skin's fragment (test/instructions-sync.test.ts enforces it). -->
+<!-- substrate-conventions vsynoptic-1.0.0-alpha.8+9d0bf8e1 — opencode skin; plugin-owned, do not edit. Edit your own AGENTS.md instead. Body is shared with the Claude skin's fragment (test/instructions-sync.test.ts enforces it). -->
 
 # Substrate interaction conventions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnmal-ai/cortext-opencode",
-  "version": "1.0.0-alpha.7",
+  "version": "1.0.0-alpha.8",
   "description": "Cortext — the OpenCode skin: cold-start injection via experimental.chat.system.transform, bundling the @mnmal-ai/synoptic host into a committed dist artifact. Installed as an OpenCode plugin (\"plugin\": [\"@mnmal-ai/cortext-opencode\"]). Published to npm, not the Claude marketplace.",
   "license": "Apache-2.0",
   "repository": {
@@ -17,7 +17,6 @@
     "dist",
     "skills",
     "instructions",
-    "commands",
     "README.md"
   ],
   "publishConfig": {
@@ -25,7 +24,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@mnmal-ai/synoptic": "1.0.0-alpha.7",
+    "@mnmal-ai/synoptic": "1.0.0-alpha.8",
     "@opencode-ai/plugin": "^1.18.35",
     "@opencode/plugin": "^2.0.24",
     "@types/node": "^26.6.4",

package/skills/substrate-run/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: substrate-run
+description: "Run a short TypeScript script against Substrate with `substrate run`, so many reads and writes cost one tool call and return one small result. Use for multi-step store work: censuses and counts, joins across types, recall-then-hydrate, and batch writes driven by reads. Do NOT use for a single lookup or a single write; the substrate MCP tools are simpler there. Requires substrate >= 1.0.0-alpha.6."
+---
+
+`substrate run` imports one `.mts` script, calls its default export with a signed
+`ScriptContext`, and prints one JSON report. Many queries and mutations run in a
+single tool call, and only the result the script returns reaches your context.
+
+## 0. Find the binary and the identity
+
+**Requires substrate >= 1.0.0-alpha.6.** Older binaries have no `run` subcommand.
+
+Both come from the `substrate` server in `opencode.json` (`mcp.servers.substrate`,
+project or user level):
+
+- **The binary** is its `command` array minus the trailing `mcp`: either
+  `node /abs/path/to/substrate.js`, or `npx -y @mnmal-ai/substrate@next`.
+- **The identity** is its `environment`: `SUBSTRATE_URL`,
+  `SUBSTRATE_AGENT_KEY_ID` and `SUBSTRATE_AGENT_KEY_PATH`. A `{env:VAR}` value
+  is already in your shell. A literal one is not, so set it on the command.
+  Use only the key's path; never read or print the key file.
+
+```bash
+node /abs/path/to/substrate.js --version
+```
+
+Write every run as one literal command, values filled in, leaving out any
+variable your shell already has:
+
+```bash
+env SUBSTRATE_URL=https://substrate.example.com:3100 SUBSTRATE_AGENT_KEY_ID=repo-opencode@host SUBSTRATE_AGENT_KEY_PATH=/abs/path/to/repo-opencode.key node /abs/path/to/substrate.js run script.mts
+```
+
+If the version is below `1.0.0-alpha.6`, stop and use the MCP tools instead.
+Say that the local substrate install is behind and that updating it unlocks
+this skill.
+
+**It refuses to run unsigned**, so a refusal names a missing identity rather
+than a broken script.
+
+## 1. When to use it, and when not to
+
+| Use `substrate run` | Use the MCP tools |
+|---|---|
+| A count or census over many rows (`queryAll` pages to the end) | One lookup by id, shortId or name |
+| A join: rows of one type, then the rows they reference | One write |
+| Recall, then fetch the bodies of the few hits worth reading | Exploring the schema |
+| A batch of writes chosen by what a read found | Anything you will read only once, row by row |
+
+The test: if you would otherwise make three or more MCP calls and pass ids from
+one call to the next, write a script.
+
+## 2. Write the script outside the repo
+
+Scripts are throwaway. Put them in the session scratchpad directory, or a temp
+directory if the harness gives you none, never in the repo.
+
+```ts
+import type { ScriptContext } from '@mnmal-ai/substrate/client';
+
+// node /abs/path/to/substrate.js run open-by-project.mts --args '{"ns":"cortext"}'
+export default async function (s: ScriptContext) {
+  const ns = String(s.args.ns ?? 'cortext');
+  const open = await s.queryAll(`${ns}/Todo`, {
+    params: { where: { status: { eq: 'open' }, archived: { eq: false } }, limit: 100 },
+    fields: { id: true, project: true }
+  });
+  const byProject: Record<string, number> = {};
+  for (const t of open) byProject[String(t.project ?? 'null')] = (byProject[String(t.project ?? 'null')] ?? 0) + 1;
+  return { total: open.length, byProject };
+}
+```
+
+The namespace is `cortext` unless `SUBSTRATE_NAMESPACE` says otherwise. Pass it
+in through `--args` instead of hardcoding it. The `import type` line is erased
+at load, so the script needs no `node_modules` beside it.
+
+The context:
+
+| Member | Does |
+|---|---|
+| `s.args` | The `--args` JSON object, frozen. `{}` when omitted |
+| `s.query(frame)` | One query frame. **Throws if any key you asked for is missing from `data`**: a rejected frame fails the run with the server's `errors` instead of reading as empty. Adds a warning when a result is truncated (`hasMore`) |
+| `s.queryAll(key, { params, fields })` | Every row of one key, paging until `hasMore` is false |
+| `s.recall({ query, namespace, type?, k?, threshold?, where?, row? })` | Hits, best first. `row` holds `id` plus the handle fields; pass `row: { body: true }` (or `true`) only on the call whose hits you will read |
+| `s.mutate(payload)` | One mutate payload. Throws by default, records without sending under `--dry-run`, sends under `--write`. Throws when the server refuses any frame |
+| `s.log(...)` | stderr only. The report owns stdout |
+| `s.kid`, `s.mode` | The signing kid and `read` / `dry-run` / `write` |
+
+## 3. Reduce in the script
+
+Return counts, ids, short handles, a verdict. Never return whole rows "to look
+at". Filtering, grouping and joining belong in the script, because what it
+returns lands in your context.
+
+When the result is large, pass `--out <file>` (beside the script). The report
+goes to the file and stdout gets one line. Then read only what you need from
+the file.
+
+## 4. Writes: dry run, read, then write
+
+The default mode is read-only, and `s.mutate` throws in it.
+
+1. Run with `--dry-run`. Each payload is recorded in `report.mutations` and
+   nothing is sent; `s.mutate` returns `null`, so do not let later logic depend
+   on its return value.
+2. Read `report.mutations`. Check the count, the ids, and a sample of the
+   params against what you intended.
+3. Re-run the same script with `--write`. It sends up to `--max-writes` frames
+   (default 50; an array under an op-key counts one per element). Raise it
+   deliberately, not by habit.
+
+The script re-reads the store on the write run, so it acts on the current state
+rather than on what the dry run saw.
+
+Transactions are per call and per op-key. Within one `s.mutate` payload, each
+array op-key is its own transaction and the single-frame op-keys share one, so
+one op-key can be refused (for example `policy_denied`) while its siblings
+land. Separate `s.mutate` calls are separate transactions. For writes that must
+land together, put them in one array under one op-key.
+
+## 5. Read the report
+
+```json
+{ "ok": true, "kid": "…", "mode": "write", "args": {}, "result": {}, "mutations": [{ "frame": {}, "applied": true }], "warnings": [], "stats": { "queries": 3, "writes": 1, "ms": 137 } }
+```
+
+- Check `ok` and the exit code (`0` ok, `1` the script failed, `2` usage or
+  configuration) before `result`. On failure `error` carries the server's
+  message.
+- **`mutations` lists every payload with `applied`, including those sent before
+  a failure.** A failed `--write` run may have written part of its batch. Read
+  this list before retrying, and make a retry skip rows that already changed.
+- `warnings` names truncated reads. A warning means the answer is incomplete;
+  switch that read to `queryAll`.
+
+Never pipe the run into `tail` or `jq` when its exit code matters. Use
+`--out`, or redirect to a file.
+
+## 6. Cut the permission prompts
+
+If OpenCode asks before each run, suggest the user allow the command in
+`opencode.json`, using the prefix from step 0:
+
+```json
+{ "permission": { "bash": { "env SUBSTRATE_URL=* node /abs/path/to/substrate.js run *": "allow" } } }
+```
+
+This covers `--write` too, just as the MCP tools write without prompting. The
+dry run in step 4 is the guard on writes, not the permission prompt.

package/{commands/substrate-setup.md → skills/substrate-setup/SKILL.md}

@@ -1,10 +1,11 @@
 ---
+name: substrate-setup
 description: Onboard this repo as a Cortext consumer under OpenCode. Probes the target Substrate, wires the substrate MCP server in opencode.json (identity-ready), installs the conventions instructions, and seeds baseline AgentRules. Run once per repo.
 ---
 
-# /substrate-setup (OpenCode) — onboard a cortext-opencode consumer
+# substrate-setup (OpenCode): onboard a cortext-opencode consumer
 
-Run these steps in order. This command is **idempotent** — re-running it never duplicates config entries or rules.
+Run these steps in order. This skill is **idempotent** — re-running it never duplicates config entries or rules.
 
 Steps 2, 5, 6, 8 are transport-agnostic and identical to the Claude skin's
 `/substrate-setup`; only the file paths and the MCP dialect differ. Where this
@@ -51,7 +52,7 @@ following and report it as ✓/✗:
 3. **Recall capability:** `GET <SUBSTRATE_URL>/substrate/v1/embed-stats` → `enabled`.
    `true` = hybrid cold-start; `false` = structural-only (degrades cleanly).
 4. **MCP package resolvable** (only if Step 4 uses the npx server form):
-   `npm view @mnmal-ai/substrate version`. It is public on npmjs.com, so a
+   `npm view @mnmal-ai/substrate@next version`. It is public on npmjs.com, so a
    failure here is a network or registry-mirror problem, not missing auth.
 
 Print a capability summary block.
@@ -67,7 +68,7 @@ Print a capability summary block.
      "$schema": "https://opencode.ai/config.json",
      "plugins": [
        {
-         "package": "@mnmal-ai/cortext-opencode",
+         "package": "@mnmal-ai/cortext-opencode@next",
          "options": {
            "kid": "<the Step-1 kid>",
            "key": "<the Step-1 key file>"
@@ -77,7 +78,7 @@ Print a capability summary block.
    }
    ```
 
-   The plain string form (`"plugins": ["@mnmal-ai/cortext-opencode"]`) also
+   The plain string form (`"plugins": ["@mnmal-ai/cortext-opencode@next"]`) also
    works — identity then comes from the env pair. **Keep exactly one entry
    per package**: as of opencode v2.0.24 the `plugins`
    arrays concatenate across global + project config and loads dedupe only
@@ -89,7 +90,19 @@ Print a capability summary block.
    npm plugins install automatically via Bun at startup (cached under
    `~/.cache/opencode/`). No registry auth is needed.
 
-2. Conventions need no step: the plugin injects them from its own package
+2. Install the skills. OpenCode loads no skills from a plugin package, so
+   copy them to the user skills directory, where every repo sees them. Bun
+   installs the plugin at startup, so restart opencode after step 1 first.
+   Re-run this after each plugin update; the copy does not track the package.
+
+   ```bash
+   PKG=$(ls -d ~/.cache/opencode/npm/@mnmal-ai/cortext-opencode@next/*/node_modules/@mnmal-ai/cortext-opencode | sort | tail -1)
+   mkdir -p ~/.config/opencode/skills && cp -R "$PKG/skills/." ~/.config/opencode/skills/
+   ```
+
+   That installs `council`, `todos`, `substrate-run` and this skill.
+
+3. Conventions need no step: the plugin injects them from its own package
    on every dispatch, so they track the installed version. If the
    repo has an older `.opencode/substrate-conventions.md` copy, delete it and its
    `"instructions"` entry; the session context names it while it is stale.
@@ -115,7 +128,7 @@ leaves empty:
     "servers": {
       "substrate": {
         "type": "local",
-        "command": ["npx", "-y", "@mnmal-ai/substrate", "mcp"],
+        "command": ["npx", "-y", "@mnmal-ai/substrate@next", "mcp"],
         "codemode": false,
         "environment": {
           "SUBSTRATE_URL": "<the url>",
@@ -212,6 +225,6 @@ set):
 ```
 
 Then summarise: SUBSTRATE_URL source, plugin entry, instructions copy, MCP
-server form, rules created vs skipped, recall tier, identity (per-project
+server form, skills installed, rules created vs skipped, recall tier, identity (per-project
 kid vs fleet default). Tell the user to restart opencode — config loads once
 at startup, and the cold-start injects on the first dispatch after that.