skillscript-runtime 0.27.0 → 0.27.2

package/examples/connectors/DataStoreTemplate/DataStoreTemplate.ts

@@ -165,4 +165,18 @@ export class DataStoreTemplate implements DataStore {
     //   - Return { id, created_at }
     throw new Error("TODO: write() — persist record; return { id, created_at }.");
   }
+
+  /**
+   * Direct lookup by substrate-assigned id (v0.13.8 — lets `data_read`
+   * inspect a record without a query roundtrip). Return `null` when the id
+   * isn't found — do NOT throw; null-on-miss is the DataStore convention
+   * (contrast SkillStore, which throws `SkillNotFoundError`). Substrates
+   * without a native by-id lookup can implement via a filtered query, but
+   * the null semantics must hold.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  async get(_id: string): Promise<PortableData | null> {
+    // TODO — fetch one record by id from your substrate; null when missing.
+    throw new Error("TODO: get() — return the record for this id, or null.");
+  }
 }

package/examples/onboarding-scaffold/file-data-store.ts

@@ -5,7 +5,7 @@
 // their concrete substrate (e.g., swap the JSON file for a Postgres
 // table, the substring match for actual full-text search, etc.).
 //
-// **Scope.** Implements `query()` + `write()` per the DataStore contract.
+// **Scope.** Implements `query()` + `write()` + `get()` per the DataStore contract.
 
 import { readFileSync, existsSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
@@ -35,7 +35,9 @@ export class FileDataStore implements DataStore {
       implementation: "FileDataStore",
       contract_version: "1.0.0",
       features: {
-        supports_fts: true,
+        // FTS is the baseline query mode — declared via `manifest().supported_modes`,
+        // not a feature flag. Flags are the closed `DataStoreFeature` set.
+        supports_writes: true,
         supports_semantic: false,
         supports_rerank: false,
       },
@@ -96,11 +98,20 @@ export class FileDataStore implements DataStore {
     return { id, created_at };
   }
 
+  /**
+   * Direct lookup by id (v0.13.8 DataStore contract). Null-on-miss —
+   * never throws for an unknown id.
+   */
+  async get(id: string): Promise<PortableData | null> {
+    return this.loadFile().find((r) => r.id === id) ?? null;
+  }
+
   async manifest(): Promise<ManifestInfo> {
     return {
       capabilities_version: "1",
       manifest: {
         kind: "file-data-store",
+        supported_modes: ["fts"],
         file_path: this.config.filePath,
         record_count: this.loadFile().length,
         supports_write: true,

package/examples/onboarding-scaffold/openai-local-model.ts

@@ -43,8 +43,10 @@ export class OpenAILocalModel implements LocalModel {
       implementation: "OpenAILocalModel",
       contract_version: "1.0.0",
       features: {
+        supports_max_tokens: true,
+        supports_timeout: false,
         supports_streaming: false,
-        supports_token_count: false,
+        supports_embedding: false,
       },
     };
   }

package/examples/onboarding-scaffold/tmux-shell-agent-connector.ts

@@ -5,9 +5,11 @@
 // with agents running in tmux sessions can wire `# Output: agent: <agent>`
 // end-to-end against this impl.
 //
-// **Scope.** Implements `deliver()` + `list_agents()` + `wake()` +
-// `manifest()` per the AgentConnector contract. `wake()` is a no-op
-// here (tmux panes are always live; wake is for harnesses with sleep modes).
+// **Scope.** Implements the full AgentConnector contract: `deliver()` +
+// `list_agents()` + `wake()` + `agent_status()` + `health_check()` +
+// `request_response()` + `manifest()`. `wake()` degrades to a no-op (tmux
+// panes are always live; wake is for harnesses with sleep modes) and
+// `request_response()` throws not-implemented (send-keys is fire-and-forget).
 
 import { spawn } from "node:child_process";
 import type {
@@ -16,6 +18,8 @@ import type {
   AgentStatus,
   DeliveryPayload,
   DeliveryReceipt,
+  RequestResponseOpts,
+  Response,
   WakeOpts,
   WakeReceipt,
 } from "skillscript-runtime/connectors";
@@ -36,7 +40,10 @@ export class TmuxShellAgentConnector implements AgentConnector {
       connector_type: "agent_connector",
       implementation: "TmuxShellAgentConnector",
       contract_version: "1.0.0",
-      features: { supports_deliver: true, supports_wake: false },
+      // AgentConnector flags are method-presence shape (one per contract
+      // method). `wake` is present but degrades to a no-op — see wake()'s
+      // `woken: false` receipt.
+      features: { deliver: true, wake: true, list_agents: true, agent_status: true },
     };
   }
 
@@ -75,10 +82,13 @@ export class TmuxShellAgentConnector implements AgentConnector {
   }
 
   async wake(agent_id: string, _opts?: WakeOpts): Promise<WakeReceipt> {
-    // tmux panes are always live; no-op wake returns immediately.
+    // tmux panes are always live — there is nothing to wake. `woken: false`
+    // is the honest receipt: the substrate performed no wake action (the
+    // contract reads false as "degraded to deliver-only").
     const session = this.config.sessionMap[agent_id];
     return {
       woken_at: Date.now(),
+      woken: false,
       ...(session !== undefined ? { session_id: session } : {}),
     };
   }
@@ -87,6 +97,32 @@ export class TmuxShellAgentConnector implements AgentConnector {
     return this.config.sessionMap[agent_id] !== undefined ? "active" : "unknown";
   }
 
+  /**
+   * Substrate liveness: is the `tmux` binary reachable? Invoked at
+   * `Registry.registerAgentConnector()` — a false return refuses the wiring
+   * early instead of failing on the first deliver.
+   */
+  async health_check(): Promise<boolean> {
+    try {
+      await this.tmux(["-V"]);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * tmux send-keys is fire-and-forget — there is no reply channel to
+   * correlate a response on. Throw not-implemented per the contract's
+   * documented pattern (see NoOpAgentConnector) rather than fake a reply.
+   */
+  async request_response(agent_id: string, _payload: DeliveryPayload, _opts: RequestResponseOpts): Promise<Response> {
+    throw new Error(
+      `TmuxShellAgentConnector: request_response(${agent_id}) not implemented — ` +
+      `tmux send-keys has no reply channel. Use deliver() for one-way output.`,
+    );
+  }
+
   async manifest(): Promise<ManifestInfo> {
     return {
       capabilities_version: "1",

package/examples/skillscripts/classify-support-ticket.skill.provenance.json

@@ -0,0 +1,10 @@
+{
+  "provenance_version": "1.0",
+  "language_version": "1.0",
+  "compiler_version": "0.1.0-dev",
+  "compiled_at": "2026-07-09T22:36:21.217Z",
+  "source_skill": {
+    "name": "classify-support-ticket"
+  },
+  "data_skills_inlined": []
+}

package/examples/skillscripts/data-store-roundtrip.skill.provenance.json

@@ -0,0 +1,10 @@
+{
+  "provenance_version": "1.0",
+  "language_version": "1.0",
+  "compiler_version": "0.1.0-dev",
+  "compiled_at": "2026-07-09T22:36:21.422Z",
+  "source_skill": {
+    "name": "data-store-roundtrip"
+  },
+  "data_skills_inlined": []
+}

package/examples/skillscripts/doc-qa-with-citations.skill.provenance.json

@@ -0,0 +1,10 @@
+{
+  "provenance_version": "1.0",
+  "language_version": "1.0",
+  "compiler_version": "0.1.0-dev",
+  "compiled_at": "2026-07-09T22:36:21.590Z",
+  "source_skill": {
+    "name": "doc-qa-with-citations"
+  },
+  "data_skills_inlined": []
+}

package/examples/skillscripts/feedback-sentiment-scan.skill.provenance.json

@@ -0,0 +1,10 @@
+{
+  "provenance_version": "1.0",
+  "language_version": "1.0",
+  "compiler_version": "0.1.0-dev",
+  "compiled_at": "2026-07-09T22:36:21.766Z",
+  "source_skill": {
+    "name": "feedback-sentiment-scan"
+  },
+  "data_skills_inlined": []
+}

package/examples/skillscripts/hello-world.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-07-06T17:54:43.615Z",
+  "compiled_at": "2026-07-09T22:36:21.957Z",
   "source_skill": {
     "name": "hello-world"
   },

package/examples/skillscripts/morning-brief.skill.md

@@ -1,23 +1,22 @@
 # Skill: morning-brief
 # Status: Draft
-# Description: Compose a daily morning brief from calendar, mailbox, and overnight notes when the cron trigger fires at 7am. Delivers via the agent: lifecycle hook to the receiving agent, who decides whether to surface to Slack / Discord / etc. Requires a `calendar` connector configured in connectors.json (the dotted `$ calendar.*` form). `model=qwen` is a representative LocalModel alias — adopters register one under whatever name fits (the bundled bootstrap registers `default`).
+# Description: Compose a daily morning brief from calendar, mailbox, and overnight notes when the cron trigger fires at 7am. Delivers via the agent: lifecycle hook to the receiving agent, who decides whether to surface to Slack / Discord / etc. Requires a `calendar` connector configured in connectors.json (the dotted `$ calendar.*` form). `model=qwen` is a representative LocalModel alias — adopters register one under whatever name fits (the bundled bootstrap registers `default`). Every leg carries a per-leg `(fallback:)` so one failed source degrades loudly instead of sinking the whole gather; BRIEF itself is fallback-bound so the output template always renders.
 # Vars: AGENT, BRIEF_HORIZON_HOURS=24
 # Triggers: cron: 0 7 * * *
-# OnError: morning-brief-degraded
 # Output: agent: ${AGENT}
 
 ${BRIEF}
 
 calendar:
-    $ calendar.list_events horizon_hours=${BRIEF_HORIZON_HOURS} -> EVENTS
+    $ calendar.list_events horizon_hours=${BRIEF_HORIZON_HOURS} -> EVENTS (fallback: "(calendar unavailable)")
 
 mailbox:
-    $ data_read mode=fts query="messages for ${AGENT}" limit=10 -> MAIL
+    $ data_read mode=fts query="messages for ${AGENT}" limit=10 -> MAIL (fallback: "(mailbox unavailable)")
 
 overnight:
-    $ data_read mode=rerank query="overnight notes and writes" limit=15 -> NOTES
+    $ data_read mode=rerank query="overnight notes and writes" limit=15 -> NOTES (fallback: "(overnight notes unavailable)")
 
 compose: needs: calendar, mailbox, overnight
-    $ llm prompt="Compose a concise morning brief. Calendar: ${EVENTS|json}. Mailbox: ${MAIL|json}. Overnight notes: ${NOTES|json}. Three sections, six bullets max each." model=qwen maxTokens=1200 -> BRIEF
+    $ llm prompt="Compose a concise morning brief. Calendar: ${EVENTS|json}. Mailbox: ${MAIL|json}. Overnight notes: ${NOTES|json}. Three sections, six bullets max each. A source marked unavailable should be reported as such, not invented." model=qwen maxTokens=1200 -> BRIEF (fallback: "(morning brief unavailable — compose failed; check the llm connector)")
 
 default: compose

package/examples/skillscripts/morning-brief.skill.provenance.json

@@ -0,0 +1,10 @@
+{
+  "provenance_version": "1.0",
+  "language_version": "1.0",
+  "compiler_version": "0.1.0-dev",
+  "compiled_at": "2026-07-09T22:36:22.134Z",
+  "source_skill": {
+    "name": "morning-brief"
+  },
+  "data_skills_inlined": []
+}

package/examples/skillscripts/queue-length-monitor.skill.provenance.json

@@ -0,0 +1,10 @@
+{
+  "provenance_version": "1.0",
+  "language_version": "1.0",
+  "compiler_version": "0.1.0-dev",
+  "compiled_at": "2026-07-09T22:36:22.313Z",
+  "source_skill": {
+    "name": "queue-length-monitor"
+  },
+  "data_skills_inlined": []
+}

package/examples/skillscripts/service-health-watch.skill.provenance.json

@@ -0,0 +1,10 @@
+{
+  "provenance_version": "1.0",
+  "language_version": "1.0",
+  "compiler_version": "0.1.0-dev",
+  "compiled_at": "2026-07-09T22:36:22.486Z",
+  "source_skill": {
+    "name": "service-health-watch"
+  },
+  "data_skills_inlined": []
+}

package/examples/skillscripts/skill-store-roundtrip.skill.provenance.json

@@ -0,0 +1,10 @@
+{
+  "provenance_version": "1.0",
+  "language_version": "1.0",
+  "compiler_version": "0.1.0-dev",
+  "compiled_at": "2026-07-09T22:36:22.672Z",
+  "source_skill": {
+    "name": "skill-store-roundtrip"
+  },
+  "data_skills_inlined": []
+}

package/examples/skillscripts/youtrack-morning-sweep.skill.provenance.json

@@ -0,0 +1,10 @@
+{
+  "provenance_version": "1.0",
+  "language_version": "1.0",
+  "compiler_version": "0.1.0-dev",
+  "compiled_at": "2026-07-09T22:36:22.850Z",
+  "source_skill": {
+    "name": "youtrack-morning-sweep"
+  },
+  "data_skills_inlined": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillscript-runtime",
-  "version": "0.27.0",
+  "version": "0.27.2",
   "description": "Runtime, compiler, lint, CLI, and dashboard for Skillscript — a small declarative language for authoring agent workflows.",
   "license": "MIT",
   "author": "Scott Shwarts <scotts@pobox.com>",