@neuralis/brain-core 0.3.2 → 0.4.1

package/skills/create-package/references/tools-and-schemas.md

@@ -26,7 +26,7 @@ So a `catalog_manage` with `action: ["list","update","delete"]` has one posture
 
 One `.json` per tool in the package-root `tools/` folder. **The tool name is the filename minus `.json`** — there is no `name` field (MCP-first), so renaming the file renames the tool and silently breaks every skill or prompt that named the old one. House style `<family>_<action>` in snake_case, not enforced. The file **is** the input schema: everything except `x-neuralis` is taken verbatim as `inputSchema`.
 
-**That name is GLOBAL to the deployment, and there is no per-package prefix.** If another installed package already declares it, exactly one entry owns it — the first-party one, otherwise the lexically-smaller `packageId` — and yours is **shadowed**: still loaded, its other tools untouched, but that name answers from the owner unless the owner is unavailable to the caller or an agent picks your package in Tool Access. Nothing is renamed for you. Pick a name nobody else will pick; `manifest-and-discovery.md` § *A tool name is global* has the rule and where the diagnostic shows up.
+**That name is GLOBAL to the deployment, and there is no per-package prefix.** If another installed package already declares it, exactly one entry owns it — the native one, otherwise the lexically-smaller `packageId` — and yours is **shadowed**: still loaded, its other tools untouched, but that name answers from the owner unless the owner is unavailable to the caller or an agent picks your package in Tool Access. Nothing is renamed for you. Pick a name nobody else will pick; `manifest-and-discovery.md` § *A tool name is global* has the rule and where the diagnostic shows up.
 
 ```json
 {
@@ -87,7 +87,7 @@ The load check accepts the bare-`http` form with or without the trailing `#`, an
 
 ### Session identity is never a tool input
 
-Seventeen names are banned as **root-level** properties: `userId`, `projectId`, `agentId`, `conversationId`, `requestId`, `toolUseId`, `delegateRunId`, `delegateMode`, `role`, `priority`, `grantedFeatures`, `spendLimits`, `llmRateLimitRpm`, `agentAccess`, `agentOwnership`, `session`, and the retired `dailyLimits`. Declaring one fails the load with `inputSchema.properties.userId is reserved session context and must not be tool input`. The fix is not to rename it — read `session.userId` in the handler. Identity always comes from the verified session, never from what the model typed.
+Nineteen names are banned as **root-level** properties: `userId`, `projectId`, `agentId`, `conversationId`, `requestId`, `toolUseId`, `delegateRunId`, `delegateMode`, `role`, `priority`, `rolePriorities`, `grantedFeatures`, `spendLimits`, `llmRateLimitRpm`, `agentAccess`, `agentOwnership`, `displayName`, `session`, and the retired `dailyLimits`. Declaring one fails the load with `inputSchema.properties.userId is reserved session context and must not be tool input`. The fix is not to rename it — read `session.userId` in the handler. Identity always comes from the verified session, never from what the model typed.
 
 The ban is **root-only by design**: `todos[].priority`, `members[].userId`, a message `role` are legitimate nested domain fields and none of them error. Only the top-level arguments object could be mistaken for caller identity.
 
@@ -217,7 +217,7 @@ For a sandboxed (WASM) package you write no dispatch switch — the build import
 
 **Presentation.** `ui.presentation` is `inline | card | explored`. Card type resolves first-match-wins: an MCP-app marker on the result, then `ui.cardType`, then `operation`, then `structuredContent.kind`/`.type` (the literal `tool.output` ignored), then the tool name, else `default`. **`ui.cardType` must match a declared card surface's `type`** — see `references/surfaces-and-design.md`.
 
-**Settled-header convention.** The chat card header draws ONE status icon, and its accessible name (`title` + `aria-label`) is the status word; there is no visible status pill. The settled status derives from `structuredContent`: `ok: true` (or a string `status` of `success`/`completed`/`pending_review`) → the green check; `ok: false` → the red X; any other string `status` becomes the icon's name, and its TONE is derived from the word by substring — a word containing `error` or `fail` draws the red X, `partial` the amber triangle, and a word containing `pending` draws the IN-FLIGHT SPINNER. Declaring `ok` on success payloads is the first-party convention. A completed tool with NO marker at all still settles (the platform floors runtime-`completed` to committed — a foreign tool cannot be forced into the convention), but two sharp edges: never reuse `status` for a domain value (an HTTP status number belongs under `httpStatus`), and never emit a settled status word containing `pending` — `pending_review` is the one floored carve-out. A card that claims to be running forever is a lie the user cannot dismiss, and the platform cannot tell it apart from a call that really is still open. The platform's own status spinner no longer splits the timeline into compositor layers, but anything YOUR card body animates still can — the prohibition, and the primitives that replace an `animate-*` utility, are in `references/surfaces-and-design.md` §Design floor.
+**Settled-header convention.** The chat card header draws ONE status icon, and its accessible name (`title` + `aria-label`) is the status word; there is no visible status pill. The settled status derives from `structuredContent`: `ok: true` (or a string `status` of `success`/`completed`/`pending_review`) → the green check; `ok: false` → the red X; any other string `status` becomes the icon's name, and its TONE is derived from the word by substring — a word containing `error` or `fail` draws the red X, `partial` the amber triangle, and a word containing `pending` draws the IN-FLIGHT SPINNER. Declaring `ok` on success payloads is the native convention. A completed tool with NO marker at all still settles (the platform floors runtime-`completed` to committed — a foreign tool cannot be forced into the convention), but two sharp edges: never reuse `status` for a domain value (an HTTP status number belongs under `httpStatus`), and never emit a settled status word containing `pending` — `pending_review` is the one floored carve-out. A card that claims to be running forever is a lie the user cannot dismiss, and the platform cannot tell it apart from a call that really is still open. The platform's own status spinner no longer splits the timeline into compositor layers, but anything YOUR card body animates still can — the prohibition, and the primitives that replace an `animate-*` utility, are in `references/surfaces-and-design.md` §Design floor.
 
 An unmatched `cardType` is not an error and not a blank: the result falls back to the **generic default card**, which is often deliberate (a host/builtin card type, a tool that only needs the standard rendering). The pre-flight warns rather than rejects for exactly that reason — but if you meant to ship your own card, that warning is the whole signal you will get.
 
@@ -241,9 +241,9 @@ An unmatched `cardType` is not an error and not a blank: the result falls back t
 | `Tool rate limit exceeded` | trust-tier rate limit — untrusted 10/min, trusted 100/min |
 | the handler got a number where you expected a rejected string | the dispatch validator coerces types; `"50"` becomes `50`. Guard on semantics, not on "it was validated" |
 | tools catalogued but every call policy-denied | an untrusted package with no explicit tool allowlist gets an **empty** one until an admin elevates it |
-| package `partial`, reason `untrusted-node` | a non-first-party package declaring the in-process runtime. Declare the sandboxed or MCP runtime instead |
+| package `partial`, reason `untrusted-node` | a non-native package declaring the in-process runtime. Declare the sandboxed or MCP runtime instead |
 
-Untrusted tools are rate-limited an order of magnitude harder and time out sooner than first-party ones; the full trust-ceiling table is in `references/runtime-and-build.md`.
+Untrusted tools are rate-limited an order of magnitude harder and time out sooner than native ones; the full trust-ceiling table is in `references/runtime-and-build.md`.
 
 ---
 

package/skills/create-package/scripts/{check-package.sh → check-package.mjs}

@@ -1,59 +1,74 @@
-#!/usr/bin/env bash
-#
-# create-package/check-package.sh — static pre-flight for a package directory.
-#
-# It catches only what fails SILENTLY — a frontmatter key nobody parses, a
-# `files[]` whitelist that ships an empty tarball, a `$schema` that loads and
-# then breaks every call, an unreachable widget, a UI entry whose stylesheet
-# never loads, compiled output one directory from where the loader looks. What
-# the loader itself reports BY NAME at install (id charset, reserved ids,
-# uriPolicies, workflow templates, most manifest validation) is NOT repeated
-# here — install and read the load status.
-#
-# ONE class here is authoring-only by construction: what a package UI entry may
-# reference. The kernel validator receives the manifest OBJECT — no package root,
-# no filesystem — so it can never inspect a file's CONTENT, and the platform
-# blocks nothing at runtime. The rules INVERT with the surface's declared
-# `assetMode`: a SELF-CONTAINED entry (the default) must inline everything, since
-# its subresource request leaves an opaque origin with no session cookie and is
-# not served; a "bundle" entry has its siblings served, and must keep every
-# reference inside the two roots that lane serves. This script is where both are
-# enforced, before either becomes a blank surface.
-#
-# Findings here are AUTHORING findings. They never set a package's load status —
-# that belongs to the contribution validator, and a new ERROR there would
-# retroactively flip already-installed packages to `error`.
-#
-# MODE comes from disk. `package.json`#neuralis or `neuralis.package.json` =
-# manifest mode. NO manifest = markdown mode (the source-package / bare-skill
-# layout): it checks package recognition, the markdown categories and their
-# frontmatter, SKIPS every manifest-dependent check and PRINTS the skip — so
-# nothing here ever reads as verified when it was not.
-#
-# CANNOT CHECK  anything needing a running platform (did it load, does a handler
-#   work, does a feature id exist). Nor your trust tier — trust is assigned by
-#   where the package came FROM, never declared in a manifest, so nothing here
-#   reads `access.trust` as a grant. Load proof, after install:
-#     bash "${SKILL_DIR}/scripts/verify-loaded.sh" <package-id>
-#
-# USAGE  bash check-package.sh <package-root>
-# EXIT   0 = no errors (warnings may print) · 1 = ERRORs · 2 = usage / no node
-# https://docs.neuralisapp.com/package-system/directory-contract
-# https://docs.neuralisapp.com/package-system/source-packages
+//
+// create-package/check-package.mjs — static pre-flight for a package directory.
+//
+// It catches only what fails SILENTLY — a frontmatter key nobody parses, a
+// `files[]` whitelist that ships an empty tarball, a `$schema` that loads and
+// then breaks every call, an unreachable widget, a UI entry whose stylesheet
+// never loads, compiled output one directory from where the loader looks. What
+// the loader itself reports BY NAME at install (id charset, reserved ids,
+// uriPolicies, workflow templates, most manifest validation) is NOT repeated
+// here — install and read the load status.
+//
+// ONE class here is authoring-only by construction: what a package UI entry may
+// reference. The kernel validator receives the manifest OBJECT — no package root,
+// no filesystem — so it can never inspect a file's CONTENT, and the platform
+// blocks nothing at runtime. The rules INVERT with the surface's declared
+// `assetMode`: a SELF-CONTAINED entry (the default) must inline everything, since
+// its subresource request leaves an opaque origin with no session cookie and is
+// not served; a "bundle" entry has its siblings served, and must keep every
+// reference inside the two roots that lane serves. This script is where both are
+// enforced, before either becomes a blank surface.
+//
+// Findings here are AUTHORING findings. They never set a package's load status —
+// that belongs to the contribution validator, and a new ERROR there would
+// retroactively flip already-installed packages to `error`.
+//
+// MODE comes from disk. `package.json`#neuralis or `neuralis.package.json` =
+// manifest mode. NO manifest = markdown mode (the source-package / bare-skill
+// layout): it checks package recognition, the markdown categories and their
+// frontmatter, SKIPS every manifest-dependent check and PRINTS the skip — so
+// nothing here ever reads as verified when it was not.
+//
+// CANNOT CHECK  anything needing a running platform (did it load, does a handler
+//   work, does a feature id exist). Nor your trust tier — trust is assigned by
+//   where the package came FROM, never declared in a manifest, so nothing here
+//   reads `access.trust` as a grant. Load proof, after install:
+//     node "${SKILL_DIR}/scripts/verify-loaded.mjs" <package-id>
+//
+// USAGE  node check-package.mjs <package-root>
+// EXIT   0 = no errors (warnings may print) · 1 = ERRORs · 2 = usage
+// https://docs.neuralisapp.com/package-system/directory-contract
+// https://docs.neuralisapp.com/package-system/source-packages
 
-set -euo pipefail
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 
-if [ "${1:-}" = "-h" ] || [ "${1:-}" = "--help" ]; then
-  sed -n '2,35p' "$0" | sed 's/^#\{0,1\} \{0,1\}//'; exit 0
-fi
-[ "$#" -eq 1 ] || { echo "usage: bash check-package.sh <package-root>" >&2; exit 2; }
-[ -d "$1" ] || { echo "ERROR  $1 is not a directory — pass the package ROOT folder" >&2; exit 2; }
-command -v node >/dev/null 2>&1 || { echo "ERROR  node not on PATH (this parses JSON with node, not jq)" >&2; exit 2; }
-
-node - "$1" "$(dirname "$0")" <<'NODE_CHECK'
-'use strict';
-const fs = require('fs'), path = require('path');
-const ROOT = process.argv[2], SCRIPT_DIR = process.argv[3], F = [];
+// `require.resolve(spec, { paths: [from] })` walks node_modules up from each
+// root, exactly as the CommonJS loader does — the platform modules below are
+// found from the package, the cwd or this script's own install.
+const require = createRequire(import.meta.url);
+const SELF = fileURLToPath(import.meta.url);
+const SCRIPT_DIR = path.dirname(SELF);
+const argv = process.argv.slice(2);
+if (argv[0] === '-h' || argv[0] === '--help') {
+  const head = fs.readFileSync(SELF, 'utf8').split('\n');
+  const end = head.findIndex((l) => !l.startsWith('//'));
+  process.stdout.write(`${head.slice(1, end).map((l) => l.replace(/^\/\/ ?/, '')).join('\n')}\n`);
+  process.exit(0);
+}
+if (argv.length !== 1) {
+  process.stderr.write('usage: node check-package.mjs <package-root>\n');
+  process.exit(2);
+}
+let isDirectory = false;
+try { isDirectory = fs.statSync(argv[0]).isDirectory(); } catch { isDirectory = false; }
+if (!isDirectory) {
+  process.stderr.write(`ERROR  ${argv[0]} is not a directory — pass the package ROOT folder\n`);
+  process.exit(2);
+}
+const ROOT = argv[0], F = [];
 const rel = (p) => path.relative(ROOT, p) || '.';
 const err = (f, m) => F.push({ lvl: 'ERROR', f, m });
 const warn = (f, m) => F.push({ lvl: 'WARN', f, m });
@@ -63,7 +78,7 @@ const json = (p) => JSON.parse(fs.readFileSync(p, 'utf8'));
 const at = (...p) => path.join(ROOT, ...p);
 
 const SKIP = new Set(['node_modules', '.git', 'dist', 'build', 'coverage', 'scripts', 'references', 'assets']);
-const DOTS = new Set(['.claude', '.agents', '.cursor', '.codex', '.gemini', '.windsurf', '.github', '.opencode', '.kilo', '.roo']);
+const DOTS = new Set(['.claude', '.agents', '.cursor', '.codex', '.gemini', '.windsurf', '.devin', '.github', '.opencode', '.kilo', '.roo']);
 const CATS = ['skills', 'instructions', 'rules', 'agents', 'docs', 'commands'];
 
 function walk(d, out = [], depth = 0) {
@@ -214,7 +229,7 @@ if (man) {
 
   // tools — the silent traps only.
   const D7 = 'http://json-schema.org/draft-07/schema#';
-  const IDENT = /^(user|project|agent|conversation|request|toolUse)Id$|^(role|priority|grantedFeatures|spendLimits|dailyLimits|llmRateLimitRpm|agentAccess|agentOwnership|session)$/;
+  const IDENT = /^(user|project|agent|conversation|request|toolUse|delegateRun)Id$|^(delegateMode|role|priority|rolePriorities|grantedFeatures|spendLimits|dailyLimits|llmRateLimitRpm|agentAccess|agentOwnership|displayName|session)$/;
   const toolCardTypes = [];
   for (const n of dir(at('tools')) ? fs.readdirSync(at('tools')).filter((x) => x.endsWith('.json')) : []) {
     const f = `tools/${n}`;
@@ -276,7 +291,7 @@ if (man) {
   }
 
   // --- cards + the surface asset contract ------------------------------------
-  // TWO renderers exist: `direct` (first-party compiled React, registered by the
+  // TWO renderers exist: `direct` (native compiled React, registered by the
   // package's OWN host entrypoint) and `iframe` (every sandboxed path). An
   // asset-backed iframe entry lives under its own canonical
   // `app/surfaces/{kind}/{surfaceId}/` root — widget `{surfaceId}` is its `type`,
@@ -477,14 +492,14 @@ if (man) {
       return;
     }
     if (renderer === 'direct') {
-      warn(MF, `${L} renderer "direct" renders only under an ASSIGNED first-party tier — a dropped package must use "iframe"`);
+      warn(MF, `${L} renderer "direct" renders only under an ASSIGNED native tier — a dropped package must use "iframe"`);
       return;
     }
     if (renderer !== 'iframe') return;
     const url = typeof render.url === 'string' ? render.url.trim() : '';
     if (!url) { err(MF, `${L} renderer "iframe" with no "url" — nothing to load`); return; }
     if (isAbsUrl(url)) {
-      warn(MF, `${L} absolute iframe url "${url}" loads only under an ASSIGNED trusted/first-party tier — the tier comes from where the package was installed FROM, never from access.trust; an untrusted package's absolute surface is dropped from the snapshot fail-closed`);
+      warn(MF, `${L} absolute iframe url "${url}" loads only under an ASSIGNED trusted/native tier — the tier comes from where the package was installed FROM, never from access.trust; an untrusted package's absolute surface is dropped from the snapshot fail-closed`);
       if (declaredMode === 'bundle') {
         warn(MF, `${label}: "assetMode":"bundle" is IGNORED on an absolute url — the platform serves bundle subresources only for an entry under the surface's own asset root.`);
       }
@@ -661,8 +676,8 @@ if (man) {
   if (rt.skillScripts !== undefined && rt.skillScripts !== 'none') need.push(`runtime.skillScripts "${rt.skillScripts}" (validation fails below trusted — declare "none" or omit)`);
   if (pm.exec === true || pm.net === 'full' || pm.fs === 'full') need.push('runtime.permissions exec / net:"full" / fs:"full" (rejected outright when untrusted)');
   if (need.length) warn(MF, `${need.join(' · ')} — ${TIER}`);
-  if (rt.type === 'node') warn(MF, `runtime.type "node" runs IN-PROCESS and needs an ASSIGNED first-party tier — elsewhere it loads PARTIAL ("untrusted-node") and every handler errors. Use "wasm"`);
-  if (rt.type === 'mcp') warn(MF, `runtime.type "mcp" spawns a subprocess as the HOST USER and needs an ASSIGNED first-party tier — elsewhere it loads PARTIAL ("untrusted-mcp"), nothing spawns and every handler errors. "wasm" is the only code runtime below first-party. Use "wasm"`);
+  if (rt.type === 'node') warn(MF, `runtime.type "node" runs IN-PROCESS and needs an ASSIGNED native tier — elsewhere it loads PARTIAL ("untrusted-node") and every handler errors. Use "wasm"`);
+  if (rt.type === 'mcp') warn(MF, `runtime.type "mcp" spawns a subprocess as the HOST USER and needs an ASSIGNED native tier — elsewhere it loads PARTIAL ("untrusted-mcp"), nothing spawns and every handler errors. "wasm" is the only code runtime below native. Use "wasm"`);
   if (rt.type === 'mcp' && !(rt.entry && rt.entry.command)) warn(MF, 'runtime.type "mcp" without runtime.entry.command — nothing spawns, so it loads PARTIAL ("runtime-unavailable")');
 
   // compiled output — the loader looks ONLY under dist/src/**.
@@ -689,7 +704,6 @@ const e = F.filter((x) => x.lvl === 'ERROR').length;
 const sk = F.filter((x) => x.lvl === 'SKIP').length;
 out.write(`\n${e} error(s), ${F.length - e - sk} warning(s)${sk ? `, ${sk} check(s) SKIPPED` : ''} — ${path.basename(ROOT)}\n`);
 if (e === 0) out.write(MODE === 'manifest'
-  ? 'Static checks pass — that proves NOTHING about loading. Install, then verify-loaded.sh.\n'
-  : 'Static checks pass for what markdown can carry — that proves NOTHING about discovery.\nThe files must be indexed by a sync first, then: verify-loaded.sh "<slug>://<path>?project=<p>&scope=…".\n');
+  ? 'Static checks pass — that proves NOTHING about loading. Install, then verify-loaded.mjs.\n'
+  : 'Static checks pass for what markdown can carry — that proves NOTHING about discovery.\nThe files must be indexed by a sync first, then: verify-loaded.mjs "<slug>://<path>?project=<p>&scope=…".\n');
 process.exit(e > 0 ? 1 : 0);
-NODE_CHECK