skillscript-runtime 0.2.7 → 0.2.9

package/dist/help-content.js

@@ -0,0 +1,469 @@
+// Static help content for the `help` MCP tool (v0.2.8). Cold-agent
+// language discovery — answers the minimum-viable questions a new
+// author needs to write a working skill, without needing to load the
+// full language reference.
+//
+// Content layout:
+//   quickstart  — ~500-token introduction; 6 questions + 1 worked example
+//   ops         — op symbol legend with one-line shapes per op
+//   frontmatter — header keys + values
+//   examples    — three canonical worked skills (minimal / threshold / branching)
+//   connectors  — short explainer; delegates dynamic data to runtime_capabilities
+//   lint-codes  — list of lint rules organized by tier
+//
+// Token estimates per topic are approximate; help() output is intended
+// for an agent's working context, not for human reading.
+const QUICKSTART = `# Skillscript — quickstart
+
+Skillscript is a declarative language for authoring agent workflows. A
+skill is a small program with named targets composed of typed ops. The
+runtime walks dependencies backward from the goal target (declared via
+\`default:\`) and dispatches each op in topological order.
+
+## 1. Shape of a skill file
+
+\`\`\`
+# Skill: my-skill                      ← required: skill name
+# Description: What this skill does    ← optional but recommended
+# Status: Approved                     ← required: Draft | Approved | Disabled
+# Vars: NAME=default-value, OTHER      ← optional: declared variables
+# Triggers: cron: 0 9 * * *            ← optional: autonomous-dispatch sources
+
+target_a:                              ← a named block of ops
+    @ curl -s https://example.com -> RAW
+    ~ prompt="Summarize: $(RAW)" -> SUMMARY
+
+target_b: target_a                     ← Make-style: target_b depends on target_a
+    ! $(SUMMARY)
+
+default: target_b                      ← goal target the runtime walks toward
+\`\`\`
+
+## 2. Op symbol legend
+
+| Op | Meaning |
+|---|---|
+| \`$ tool args -> VAR\` | MCP tool invocation; binds result to VAR |
+| \`~ prompt="..." -> VAR\` | LocalModel call; binds output |
+| \`> mode=... query=... limit=N -> VAR\` | Memory retrieval |
+| \`@ command args -> VAR\` | Shell exec (structural sandbox; \`@ unsafe\` for full bash) |
+| \`! text\` | Emit text to the user / output channel |
+| \`?? prompt -> VAR\` | Ask user (interactive mode only) |
+| \`$set NAME=value\` | Explicit variable binding |
+| \`& skill-name args -> VAR\` | Inline a data-skill |
+
+## 3. Result binding
+
+Most ops accept \`-> VAR\` to bind their output. Reference later via \`$(VAR)\`.
+Optional \`(fallback: "default")\` after \`-> VAR\` binds the fallback on dispatch
+error instead of propagating.
+
+## 4. Branching
+
+\`\`\`
+if $(VERDICT) == "urgent":
+    ! sound the alarm
+elif $(COUNT) > "10":
+    ! threshold breached: $(COUNT) items
+else:
+    ! all clear
+\`\`\`
+
+Numeric comparison (\`<\` / \`>\` / \`<=\` / \`>=\`) coerces both sides via Number();
+non-numeric operands raise TypeMismatchError.
+
+## 5. Iteration
+
+\`\`\`
+foreach M in $(MEMORIES):
+    ! Processing $(M.id): $(M.summary)
+\`\`\`
+
+## 6. How to see what's broken
+
+- \`lint_skill({source})\` — diagnostics across tier-1 (errors), tier-2 (warnings), tier-3 (advisories)
+- \`compile_skill({source, inputs?})\` — render the compiled artifact + surface compile errors
+- \`runtime_capabilities()\` — discover wired connectors, models, shell-exec mode
+
+## Worked end-to-end example
+
+\`\`\`
+# Skill: morning-temperature-alert
+# Description: Cron-fired check; alerts when overnight temp drops below threshold
+# Status: Approved
+# Vars: LOCATION=Asheville,NC, THRESHOLD=40
+# Triggers: cron: 0 7 * * *
+
+fetch:
+    @ curl -s "wttr.in/$(LOCATION|url)?format=j1" -> RAW (fallback: "")
+
+evaluate: fetch
+    ~ prompt="Extract overnight low temperature in F from this JSON. Reply with only the number: $(RAW)" model=qwen -> TEMP
+
+alert: evaluate
+    if $(TEMP|trim) < $(THRESHOLD):
+        ! Cold morning: overnight low $(TEMP|trim)°F (threshold $(THRESHOLD)°F)
+    else:
+        ! Temp ok: $(TEMP|trim)°F
+
+default: alert
+\`\`\`
+
+Use \`help({topic: "ops"})\`, \`help({topic: "frontmatter"})\`, \`help({topic: "examples"})\`,
+\`help({topic: "connectors"})\`, or \`help({topic: "lint-codes"})\` for deeper sections.
+`;
+const OPS = `# Op symbols — full reference
+
+## Dispatch ops (bind a result)
+
+### \`$\` — MCP tool invocation
+
+\`\`\`
+$ tool_name arg1=value1 arg2=value2 -> VAR [(fallback: "default")]
+$ connector.tool_name args -> VAR
+\`\`\`
+
+Calls an MCP tool. Without an explicit connector prefix, routes to the
+\`primary\` MCP connector. Fallback binds when dispatch errors.
+
+**Built-in (v0.2.8):** \`$ execute_skill skill_name=child -> RESULT\` invokes
+another stored skill end-to-end without requiring an MCP connector — pass
+input vars as additional kwargs.
+
+### \`~\` — LocalModel call
+
+\`\`\`
+~ prompt="..." model=qwen maxTokens=400 -> VAR [(fallback: "...")]
+\`\`\`
+
+LLM call against a configured LocalModel. \`model\` selects the named model;
+default is \`default\`. Multi-line prompts via \`"..."\` are supported (parser
+folds quoted-string continuations).
+
+### \`>\` — Memory retrieval
+
+\`\`\`
+> mode=fts query="..." limit=20 -> VAR [(fallback: "...")]
+\`\`\`
+
+Queries the configured MemoryStore. \`mode\` is substrate-specific
+(\`fts\` / \`semantic\` / \`rerank\` are common). \`limit\` is required.
+
+### \`@\` — Shell exec
+
+\`\`\`
+@ command arg1 arg2 -> VAR [(fallback: "...")]
+@ unsafe full-shell-command -> VAR
+\`\`\`
+
+Default mode: structural spawn — one binary, no shell metacharacters,
+no pipes/redirects. \`@ unsafe\` opts into full bash; lint-flags tier-2.
+
+## Emission + control ops
+
+### \`!\` — Emit text
+
+\`\`\`
+! Hello, $(NAME)!
+\`\`\`
+
+One-line literal emission. Variables substitute. No result binding.
+
+### \`??\` — Ask user
+
+\`\`\`
+?? Are you sure? -> CONFIRM
+\`\`\`
+
+Interactive only. Autonomous-mode dispatch fails with a clean error.
+
+### \`$set\` — Explicit binding
+
+\`\`\`
+$set NAME=value
+$set NAME=$(OTHER_VAR|trim)
+\`\`\`
+
+### \`&\` — Inline data-skill
+
+\`\`\`
+& source-skill-name arg=value -> VAR
+\`\`\`
+
+References a \`# Type: data\` skill; the compiler inlines its emitted text
+at compile time so the compiled artifact is a single resolved document.
+
+## Pipe filters
+
+Apply on \`$(VAR|filter)\` references; chain left-to-right.
+
+| Filter | Effect |
+|---|---|
+| \`url\` | encodeURIComponent |
+| \`shell\` | POSIX single-quote escape |
+| \`json\` | JSON.stringify |
+| \`trim\` | Whitespace trim |
+| \`length\` | Array element count or string char count (v0.2.5) |
+
+## Conditional grammar
+
+\`\`\`
+if $(VAR):                            ← truthy check
+if $(VAR) == "literal":               ← equality vs literal
+if $(VAR) == $(OTHER):                ← equality vs ref
+if $(VAR) != "literal":               ← inequality
+if $(N) < "10":                       ← numeric comparison (v0.2.5)
+if $(N) >= $(THRESHOLD):              ← numeric vs ref
+if $(M.id) in $(SEEN):                ← set membership
+if $(M.id) not in $(SEEN):
+\`\`\`
+
+Branches via \`if:\` / \`elif COND:\` / \`else:\`. The \`else:\` after a target
+body is a separate error-handler block (distinguished by indentation scope).
+`;
+const FRONTMATTER = `# Frontmatter headers — full reference
+
+Skill files open with \`# Key: value\` headers. Order isn't significant.
+
+## Required
+
+- \`# Skill: <name>\` — identity. Reserved keywords (\`default\`, \`needs\`, etc.) rejected.
+- \`# Status: Draft | Approved | Disabled\` — lifecycle state. Only Approved skills fire via triggers.
+
+## Common
+
+- \`# Description: <prose>\` — human-readable explanation; surfaces in dashboards.
+- \`# Type: procedural | data\` — \`procedural\` (default) for runtime-fired skills; \`data\` for compile-time-inlined fragments referenced by \`&\` ops.
+- \`# Vars: NAME=default, OTHER\` — declared variables. \`NAME=default\` provides a default; bare \`NAME\` is required at invocation.
+- \`# Triggers: cron: 0 9 * * *, session: start\` — autonomous-dispatch sources. Comma-separated entries split by source-keyword boundary; cron expressions with commas (\`30,45 9 * * 1-5\`) parse correctly.
+- \`# Output: text | slack: chan | prompt-context: agent | template: agent | file: path | card: id | none\` — output routing.
+- \`# OnError: <fallback-skill-name>\` — error-handler skill invoked when an op fails and no target-level \`else:\` catches.
+
+## Augmenting / Template only
+
+- \`# Delivery-context: <prose>\` — routed to the receiving agent alongside the augment payload. v0.2.6.
+- \`# Templates: <skill_name>, <skill_name>\` — comma-separated Template-skill names the receiving agent may fetch as follow-on actions. v0.2.6.
+
+(Both fire \`unused-augmenting-header\` lint warning if set on a Headless skill — one with no \`prompt-context:\` or \`template:\` output declaration.)
+
+## Capabilities + retrieval
+
+- \`# Requires: <namespace>:<key> -> VAR (fallback: "value")\` — declares external input requirements. \`user-var:\` or \`system-var:\` namespaces. Cascades resolve at compile.
+- \`# Requires: connector_type.feature_flag\` — capability-style requires (e.g., \`local_model.streaming\`); validated against \`runtime_capabilities\`.
+
+## Performance
+
+- \`# Timeout: <seconds>\` — skill-wide timeout. Falls back to per-op or runtime defaults.
+
+## Trigger declaration forms
+
+\`\`\`
+# Triggers: cron: 30,45 9 * * 1-5
+# Triggers: session: start, session: end
+# Triggers: cron: 0 7 * * *, agent-event: drift-detected
+\`\`\`
+
+Trigger sources today: \`cron\` (poll-based), \`session\` (\`start\` / \`end\` phases). Parse-only in v0.2: \`event\`, \`agent-event\`, \`file-watch\`, \`sensor\` (firing lands in v1.0).
+`;
+const EXAMPLES = `# Three canonical worked skills
+
+## 1. Minimal (single target, no dependencies)
+
+\`\`\`
+# Skill: hello
+# Description: The canonical first-run example.
+# Status: Approved
+# Vars: WHO=world
+
+greet:
+    ! Hello, $(WHO)!
+    ! Welcome to Skillscript.
+
+default: greet
+\`\`\`
+
+Demonstrates: required headers, variable defaults, \`!\` emission with substitution.
+
+## 2. Cron-fired numeric threshold + count
+
+\`\`\`
+# Skill: queue-length-monitor
+# Description: Count pending items in a queue and alert when the count exceeds threshold
+# Status: Approved
+# Vars: QUEUE_PATH=/var/queue/pending.json, THRESHOLD=10
+# Triggers: cron: */5 * * * *
+
+fetch:
+    @ cat $(QUEUE_PATH) -> ITEMS (fallback: "[]")
+
+evaluate:
+    needs: fetch
+    if $(ITEMS|length) > $(THRESHOLD):
+        ! Queue backlog: $(ITEMS|length) items pending (threshold $(THRESHOLD)). Action required.
+    else:
+        ! Queue healthy: $(ITEMS|length) items pending (under $(THRESHOLD)).
+
+default: evaluate
+\`\`\`
+
+Demonstrates: \`# Triggers:\` cron, shell \`@\` op with fallback, \`needs:\` body-line dep, numeric comparison, \`|length\` filter, \`if\` / \`else\`.
+
+## 3. LocalModel branching with agent delivery
+
+\`\`\`
+# Skill: classify-support-ticket
+# Description: Classify an incoming ticket by urgency and route to oncall when severe
+# Status: Approved
+# Vars: TICKET_BODY
+# Delivery-context: Urgent ticket triage — please assess + assign owner.
+# Templates: ticket-assignment-procedure
+# Output: prompt-context: oncall
+
+classify:
+    ~ prompt="Classify this support ticket as one of: 'critical', 'normal', 'low'. Reply with only the label. Ticket: $(TICKET_BODY)" model=qwen -> VERDICT
+
+route: classify
+    if $(VERDICT|trim) == "critical":
+        ! CRITICAL ticket needs immediate attention:
+        ! $(TICKET_BODY)
+    elif $(VERDICT|trim) == "normal":
+        ! Normal-priority ticket queued.
+    else:
+        ! Low-priority ticket logged.
+
+default: route
+\`\`\`
+
+Demonstrates: \`~\` LocalModel op, named model selection, \`|trim\` filter on LLM output, ref-vs-literal comparison, agent delivery via \`prompt-context:\`, augmenting headers (\`# Delivery-context:\` + \`# Templates:\`).
+`;
+const CONNECTORS_PROLOGUE = `# Connectors
+
+The runtime resolves \`$\` / \`~\` / \`>\` / \`# Output:\` dispatches through a
+typed registry of five contracts:
+
+| Contract | Purpose | Op |
+|---|---|---|
+| SkillStore | Skill source persistence + status lifecycle | (implicit) |
+| MemoryStore | Knowledge retrieval | \`>\` |
+| LocalModel | LLM inference | \`~\` |
+| McpConnector | MCP tool dispatch | \`$\` |
+| AgentConnector | Deliver augment/template payloads | \`# Output: prompt-context:\` / \`template:\` |
+
+Skills don't import packages — they invoke connectors. The set wired into
+this runtime, plus their feature flags, is discoverable via:
+
+  \`runtime_capabilities()\`
+
+Call that tool for the live picture of which connectors are registered,
+which feature flags they advertise, and which named instances exist
+(e.g., \`default\` / \`qwen\` LocalModels).
+
+For shell execution (\`@\` op), \`runtime_capabilities\` also reports
+\`shellExecution.mode\` (\`"structural-spawn"\`) and
+\`shellExecution.unsafe_enabled\` (whether \`@ unsafe\` is permitted in
+this deployment).
+`;
+const LINT_CODES = `# Lint rule index
+
+Three tiers per ERD §3:
+
+- **Tier-1 (error)** — blocks compile. Must fix before the skill enters the SkillStore.
+- **Tier-2 (warning)** — non-blocking but flagged. Common smell; review.
+- **Tier-3 (info)** — advisory. Often style or organizational hints.
+
+## Tier-1 (error)
+
+- \`parse-error\` — frontmatter or grammar fault surfaced by parse()
+- \`no-targets\` — skill defines no targets
+- \`no-entry-target\` — no \`default:\` declaration
+- \`orphan-target\` — target unreachable from entry via dep graph
+- \`unknown-capability\` — \`# Requires: connector.feature\` references a flag no registered connector advertises
+- \`undeclared-var\` — \`$(VAR)\` reference not in \`# Vars:\` / \`# Requires:\` / output-bound / foreach iterator / tier-1 ambient (NOW/USER/SESSION_CONTEXT/TRIGGER_TYPE/TRIGGER_PAYLOAD/ERROR_CONTEXT)
+- \`unknown-filter\` — \`|filter\` references an unregistered filter name
+- \`malformed-op-grammar\` — op body doesn't match its grammar
+- \`invalid-conditional-syntax\` — \`if\` condition doesn't match supported forms
+- \`single-equals\` — \`if $(VAR) = "..."\` instead of \`==\` (specific diagnostic)
+- \`indentation\` — tabs in indentation; mixed tabs/spaces
+- \`reserved-keyword\` — variable/target/skill name collides with a reserved word
+- \`unknown-skill-reference\` — \`&\` op references a skill not in the store
+- \`disabled-skill-reference\` — \`&\` op references a Disabled skill
+- \`credential-in-args\` — op arg looks like a secret literal
+- \`status-disabled\` — skill marked \`# Status: Disabled\`
+- \`circular-dependency\` — dep cycle between targets
+- \`missing-dependency\` — \`needs:\` references a target not declared
+- \`missing-skillstore-for-data-ref\` — \`&\` op fires without a SkillStore wired
+
+## Tier-2 (warning)
+
+- \`deprecated-question\` — bare \`?\` op (deprecated v1; compile-error in v1.x)
+- \`unsafe-shell-ambiguous-subst\` — \`$(NAME)\` inside \`@ unsafe\` body that isn't a declared variable; collides with bash command-sub syntax
+- \`unsafe-shell-op\` — \`@ unsafe\` op present; requires human review every time
+- \`unconfirmed-mutation\` — \`$\` op invokes a tool whose name suggests mutation (write/update/delete) without a preceding \`??\` confirmation
+- \`model-contention\` — async + sync ops on the same model serialize on a single runtime worker
+- \`draft-with-trigger\` — \`# Status: Draft\` skill has \`# Triggers:\` declared; triggers won't fire until Approved
+- \`reference-to-disabled-skill\` — \`&\` op references a Disabled skill (also tier-1 in some contexts)
+- \`unused-augmenting-header\` — \`# Delivery-context:\` or \`# Templates:\` set on a skill with no agent-bound output (v0.2.6)
+
+## Tier-3 (info)
+
+- \`no-default-target\` — no \`default:\` declaration (relevant for data skills only; procedural skills hit tier-1)
+- \`duplicate-skill-name\` — name collides with an existing stored skill
+- \`plugin-collision\` — placeholder for v1.x plugin-loader name conflicts
+
+\`compile_skill({source})\` runs the full lint preflight and reports
+findings in the \`errors\` + \`warnings\` arrays. \`lint_skill({source})\`
+returns the same diagnostics without compiling.
+`;
+export function helpResponse(topic, runtimeVersion, registry) {
+    if (topic === null) {
+        return {
+            topic: null,
+            version: runtimeVersion,
+            content: QUICKSTART,
+            available_topics: ["ops", "frontmatter", "examples", "connectors", "lint-codes"],
+        };
+    }
+    let content;
+    switch (topic) {
+        case "ops":
+            content = OPS;
+            break;
+        case "frontmatter":
+            content = FRONTMATTER;
+            break;
+        case "examples":
+            content = EXAMPLES;
+            break;
+        case "connectors":
+            content = renderConnectorsTopic(registry);
+            break;
+        case "lint-codes":
+            content = LINT_CODES;
+            break;
+        default:
+            content = `# Unknown topic '${topic}'\n\nValid topics: ops, frontmatter, examples, connectors, lint-codes`;
+    }
+    return { topic, version: runtimeVersion, content };
+}
+function renderConnectorsTopic(registry) {
+    if (registry === undefined)
+        return CONNECTORS_PROLOGUE;
+    const summary = [
+        `\n## Wired in this runtime`,
+        ``,
+        `*Call \`runtime_capabilities()\` for the full discovery payload.*`,
+        ``,
+    ];
+    const ss = registry.listSkillStores();
+    const ms = registry.listMemoryStores();
+    const lm = registry.listLocalModels();
+    const mc = registry.listMcpConnectors();
+    const ac = registry.listAgentConnectors();
+    summary.push(`- SkillStores: ${ss.length === 0 ? "(none)" : ss.map((e) => `${e.name} (${e.ctor.name})`).join(", ")}`);
+    summary.push(`- MemoryStores: ${ms.length === 0 ? "(none)" : ms.map((e) => `${e.name} (${e.ctor.name})`).join(", ")}`);
+    summary.push(`- LocalModels: ${lm.length === 0 ? "(none)" : lm.map((e) => e.name).join(", ")}`);
+    summary.push(`- McpConnectors: ${mc.length === 0 ? "(none)" : mc.map((e) => `${e.name} (${e.ctor.name})`).join(", ")}`);
+    summary.push(`- AgentConnectors: ${ac.length === 0 ? "(none — defaults to NoOp)" : ac.map((e) => `${e.name} (${e.ctor.name})`).join(", ")}`);
+    return CONNECTORS_PROLOGUE + summary.join("\n");
+}
+//# sourceMappingURL=help-content.js.map

package/dist/help-content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help-content.js","sourceRoot":"","sources":["../src/help-content.ts"],"names":[],"mappings":"AAAA,mEAAmE;AACnE,kEAAkE;AAClE,qEAAqE;AACrE,2BAA2B;AAC3B,EAAE;AACF,kBAAkB;AAClB,0EAA0E;AAC1E,+DAA+D;AAC/D,uCAAuC;AACvC,kFAAkF;AAClF,kFAAkF;AAClF,uDAAuD;AACvD,EAAE;AACF,uEAAuE;AACvE,yDAAyD;AAIzD,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkGlB,CAAC;AAEF,MAAM,GAAG,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4GX,CAAC;AAEF,MAAM,WAAW,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA2CnB,CAAC;AAEF,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAsEhB,CAAC;AAEF,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;CA0B3B,CAAC;AAEF,MAAM,UAAU,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkDlB,CAAC;AAEF,MAAM,UAAU,YAAY,CAC1B,KAAoB,EACpB,cAAsB,EACtB,QAAmB;IAEnB,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,OAAO;YACL,KAAK,EAAE,IAAI;YACX,OAAO,EAAE,cAAc;YACvB,OAAO,EAAE,UAAU;YACnB,gBAAgB,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,CAAC;SACjF,CAAC;IACJ,CAAC;IACD,IAAI,OAAe,CAAC;IACpB,QAAQ,KAAK,EAAE,CAAC;QACd,KAAK,KAAK;YAAU,OAAO,GAAG,GAAG,CAAC;YAAC,MAAM;QACzC,KAAK,aAAa;YAAE,OAAO,GAAG,WAAW,CAAC;YAAC,MAAM;QACjD,KAAK,UAAU;YAAK,OAAO,GAAG,QAAQ,CAAC;YAAC,MAAM;QAC9C,KAAK,YAAY;YAAG,OAAO,GAAG,qBAAqB,CAAC,QAAQ,CAAC,CAAC;YAAC,MAAM;QACrE,KAAK,YAAY;YAAG,OAAO,GAAG,UAAU,CAAC;YAAC,MAAM;QAChD;YACE,OAAO,GAAG,oBAAoB,KAAK,uEAAuE,CAAC;IAC/G,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC;AACrD,CAAC;AAED,SAAS,qBAAqB,CAAC,QAAmB;IAChD,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,mBAAmB,CAAC;IACvD,MAAM,OAAO,GAAa;QACxB,4BAA4B;QAC5B,EAAE;QACF,mEAAmE;QACnE,EAAE;KACH,CAAC;IACF,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,EAAE,CAAC;IACtC,MAAM,EAAE,GAAG,QAAQ,CAAC,gBAAgB,EAAE,CAAC;IACvC,MAAM,EAAE,GAAG,QAAQ,CAAC,eAAe,EAAE,CAAC;IACtC,MAAM,EAAE,GAAG,QAAQ,CAAC,iBAAiB,EAAE,CAAC;IACxC,MAAM,EAAE,GAAG,QAAQ,CAAC,mBAAmB,EAAE,CAAC;IAC1C,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtH,OAAO,CAAC,IAAI,CAAC,mBAAmB,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvH,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAChG,OAAO,CAAC,IAAI,CAAC,oBAAoB,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACxH,OAAO,CAAC,IAAI,CAAC,sBAAsB,EAAE,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,2BAA2B,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7I,OAAO,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAClD,CAAC"}

package/dist/mcp-server.d.ts

@@ -27,6 +27,8 @@ import type { Registry } from "./connectors/registry.js";
  *   lint_skill({source?|name})     → diagnostics across tiers (v0.2.3)
  *   compile_skill({source?|name, inputs?})→ rendered artifact + errors (v0.2.3)
  *   skill_write({name, source, overwrite?})→ commit to SkillStore (write, v0.2.3)
+ *   execute_skill({skill_name, inputs?, mechanical?})→ run + return result (write, v0.2.8)
+ *   help({topic?})                 → cold-agent language discovery (read, v0.2.8)
  */
 export interface JsonRpcRequest {
     jsonrpc: "2.0";
@@ -84,6 +86,8 @@ export declare class McpServer {
      */
     runStdio(): void;
     private registerBuiltinTools;
+    private executeSkill;
+    private help;
     private lintSkill;
     private compileSkill;
     private skillWrite;

package/dist/mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAmC,MAAM,uBAAuB,CAAC;AACzF,OAAO,KAAK,EAAE,SAAS,EAAgD,MAAM,gBAAgB,CAAC;AAC9F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAMzD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1D;AAED,MAAM,MAAM,eAAe,GAAG,sBAAsB,GAAG,oBAAoB,CAAC;AAI5E,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;IACvB,kGAAkG;IAClG,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,+FAA+F;IAC/F,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,wFAAwF;IACxF,WAAW,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IACpC,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAKD,qBAAa,SAAS;IAIR,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAEJ,IAAI,EAAE,aAAa;IAKhD,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAIjC,SAAS,IAAI,OAAO,EAAE;IAIhB,MAAM,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAqD3D;;;;OAIG;IACH,QAAQ,IAAI,IAAI;IAyBhB,OAAO,CAAC,oBAAoB;YA0Nd,SAAS;YAyBT,YAAY;YAoDZ,UAAU;IAiCxB;;;OAGG;YACW,aAAa;YAWb,mBAAmB;CA2BlC"}
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAmC,MAAM,uBAAuB,CAAC;AACzF,OAAO,KAAK,EAAE,SAAS,EAAgD,MAAM,gBAAgB,CAAC;AAC9F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAYzD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAIH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,KAAK,CAAC;IACf,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAC3B,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;CAC1D;AAED,MAAM,MAAM,eAAe,GAAG,sBAAsB,GAAG,oBAAoB,CAAC;AAI5E,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC9D;AAED,MAAM,WAAW,aAAa;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,UAAU,CAAC;IACvB,kGAAkG;IAClG,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,+FAA+F;IAC/F,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,wFAAwF;IACxF,WAAW,CAAC,EAAE,OAAO,GAAG,WAAW,CAAC;IACpC,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAKD,qBAAa,SAAS;IAIR,OAAO,CAAC,QAAQ,CAAC,IAAI;IAHjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAmC;IACzD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAEJ,IAAI,EAAE,aAAa;IAKhD,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAIjC,SAAS,IAAI,OAAO,EAAE;IAIhB,MAAM,CAAC,GAAG,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAqD3D;;;;OAIG;IACH,QAAQ,IAAI,IAAI;IAyBhB,OAAO,CAAC,oBAAoB;YAiQd,YAAY;YAiFZ,IAAI;YAOJ,SAAS;YAyBT,YAAY;YAoDZ,UAAU;IAiCxB;;;OAGG;YACW,aAAa;YAWb,mBAAmB;CA2BlC"}

package/dist/mcp-server.js

@@ -2,6 +2,8 @@ import { healthMetrics } from "./metrics.js";
 import { lint } from "./lint.js";
 import { compile } from "./compile.js";
 import { LintFailureError } from "./errors.js";
+import { executeSkillByName, RecursionDepthExceededError, SkillNotFoundForCompositionError, } from "./composition.js";
+import { helpResponse } from "./help-content.js";
 const MCP_PROTOCOL_VERSION = "2024-11-05";
 const SERVER_NAME = "skillscript-runtime";
 export class McpServer {
@@ -10,7 +12,7 @@ export class McpServer {
     version;
     constructor(deps) {
         this.deps = deps;
-        this.version = deps.serverVersion ?? "0.2.7";
+        this.version = deps.serverVersion ?? "0.2.9";
         this.registerBuiltinTools();
     }
     registerTool(tool) {
@@ -311,6 +313,127 @@ export class McpServer {
             },
             handler: async (args) => this.skillWrite(args),
         });
+        // ─── v0.2.8 — composition + discovery ──────────────────────────────────
+        this.registerTool({
+            name: "execute_skill",
+            description: "Execute a stored skill end-to-end against the runtime's wired connectors. Returns {skill_name, final_vars, transcript, outputs, errors, target_order}. `mechanical: true` previews dispatch without firing $/~/@/?? ops (TestFlight mode). Recursion-depth-guarded for composition chains (default 10). Write operation.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    skill_name: { type: "string", description: "Skill name as stored in the SkillStore." },
+                    inputs: {
+                        type: "object",
+                        additionalProperties: { type: "string" },
+                        description: "Optional `# Vars:` overrides keyed by variable name.",
+                    },
+                    mechanical: {
+                        type: "boolean",
+                        description: "When true, $/~/@/?? ops bind placeholders instead of firing. Recurses through nested execute_skill calls.",
+                        default: false,
+                    },
+                },
+                required: ["skill_name"],
+            },
+            handler: async (args) => this.executeSkill(args),
+        });
+        this.registerTool({
+            name: "help",
+            description: "Cold-agent language discovery. `help()` returns a ~500-token quickstart. `help({topic})` returns a deeper section. Topics: ops / frontmatter / examples / connectors / lint-codes. Read-only.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    topic: {
+                        type: "string",
+                        enum: ["ops", "frontmatter", "examples", "connectors", "lint-codes"],
+                        description: "Optional topic for a deeper section. Omit for the quickstart.",
+                    },
+                },
+            },
+            handler: async (args) => this.help(args),
+        });
+    }
+    async executeSkill(args) {
+        const skillName = args["skill_name"];
+        if (typeof skillName !== "string" || skillName === "") {
+            throw new Error("execute_skill: `skill_name` is required (non-empty string).");
+        }
+        const inputs = args["inputs"] ?? {};
+        const mechanical = args["mechanical"] === true;
+        // Build an ExecuteContext for the call. The MCP tool entry is the
+        // top-level — recursionDepth starts at 0 and increments inside
+        // executeSkillByName.
+        if (this.deps.registry === undefined) {
+            throw new Error("execute_skill: runtime registry not configured (McpServerDeps.registry missing).");
+        }
+        const ctx = {
+            registry: this.deps.registry,
+            mechanical,
+            recursionDepth: 0,
+        };
+        try {
+            const result = await executeSkillByName(skillName, inputs, {
+                skillStore: this.deps.skillStore,
+                ctx,
+            });
+            return {
+                skill_name: result.skill_name,
+                final_vars: result.final_vars,
+                transcript: result.transcript,
+                outputs: result.outputs,
+                errors: result.errors,
+                target_order: result.target_order,
+                mechanical,
+            };
+        }
+        catch (err) {
+            if (err instanceof SkillNotFoundForCompositionError) {
+                return {
+                    skill_name: null,
+                    final_vars: {},
+                    transcript: [],
+                    outputs: {},
+                    errors: [{ class: "SkillNotFoundError", opKind: "execute_skill", target: "(root)", message: err.message }],
+                    target_order: [],
+                    mechanical,
+                };
+            }
+            if (err instanceof RecursionDepthExceededError) {
+                return {
+                    skill_name: skillName,
+                    final_vars: {},
+                    transcript: [],
+                    outputs: {},
+                    errors: [{ class: "RecursionDepthExceededError", opKind: "execute_skill", target: "(root)", message: err.message, chain: err.chain }],
+                    target_order: [],
+                    mechanical,
+                };
+            }
+            if (err instanceof LintFailureError) {
+                return {
+                    skill_name: skillName,
+                    final_vars: {},
+                    transcript: [],
+                    outputs: {},
+                    errors: [{ class: "LintFailureError", opKind: "execute_skill", target: "(root)", message: err.message }],
+                    target_order: [],
+                    mechanical,
+                };
+            }
+            // Unexpected — surface as a structured error rather than throw.
+            return {
+                skill_name: skillName,
+                final_vars: {},
+                transcript: [],
+                outputs: {},
+                errors: [{ class: err.name, opKind: "execute_skill", target: "(root)", message: err.message }],
+                target_order: [],
+                mechanical,
+            };
+        }
+    }
+    async help(args) {
+        const topic = typeof args["topic"] === "string" ? args["topic"] : null;
+        return helpResponse(topic, this.version, this.deps.registry);
     }
     // ─── v0.2.3 authoring-lifecycle handlers ───────────────────────────────────
     async lintSkill(args) {