skillscript-runtime 0.7.2 → 0.7.3

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

@@ -0,0 +1,95 @@
+// Onboarding scaffold: file-backed MemoryStore. v0.7.3.
+//
+// JSON file as the substrate; simple JS substring + token match for "fts"
+// queries; reranks by recency. Adopters copy this file and modify for
+// their concrete substrate (e.g., swap the JSON file for a Postgres
+// table, the substring match for actual full-text search, etc.).
+//
+// **Scope.** Read-only `query()` per the v0.7.2 MemoryStore contract.
+// `write()` is deferred to v0.8.x bundled with the auth model — when
+// that lands, extend this file with the matching `write()` method.
+
+import { readFileSync, existsSync } from "node:fs";
+import type {
+  MemoryStore,
+  PortableMemory,
+  QueryFilters,
+  ManifestInfo,
+  StaticCapabilities,
+} from "skillscript-runtime/connectors";
+
+export interface FileMemoryStoreConfig {
+  /** Absolute path to the JSON file holding the memory array. */
+  filePath: string;
+}
+
+interface FileMemoryRecord extends PortableMemory {
+  /** Optional substrate-specific fields go in `metadata`; everything top-level matches PortableMemory. */
+}
+
+export class FileMemoryStore implements MemoryStore {
+  static staticCapabilities(): StaticCapabilities {
+    return {
+      connector_type: "memory_store",
+      implementation: "FileMemoryStore",
+      contract_version: "1.0.0",
+      features: {
+        supports_fts: true,
+        supports_semantic: false,
+        supports_rerank: false,
+      },
+    };
+  }
+
+  constructor(private readonly config: FileMemoryStoreConfig) {}
+
+  async query(filters: QueryFilters): Promise<PortableMemory[]> {
+    const records = this.loadFile();
+    const queryTerms = filters.query.toLowerCase().split(/\s+/).filter((t) => t.length > 0);
+
+    // Simple substring + token match: a record matches if any query term
+    // appears in summary or detail. Adopters wire real FTS for production.
+    const scored = records
+      .map((r) => {
+        const haystack = `${r.summary} ${r.detail ?? ""}`.toLowerCase();
+        const hits = queryTerms.filter((t) => haystack.includes(t)).length;
+        return { record: r, hits };
+      })
+      .filter((s) => s.hits > 0);
+
+    // Tie-break by recency (created_at descending) so newer matches surface first.
+    scored.sort((a, b) => {
+      if (b.hits !== a.hits) return b.hits - a.hits;
+      const aTime = a.record.created_at ?? 0;
+      const bTime = b.record.created_at ?? 0;
+      return bTime - aTime;
+    });
+
+    return scored.slice(0, filters.limit).map((s) => s.record);
+  }
+
+  async manifest(): Promise<ManifestInfo> {
+    return {
+      capabilities_version: "1",
+      manifest: {
+        kind: "file-memory-store",
+        file_path: this.config.filePath,
+        record_count: this.loadFile().length,
+      },
+    };
+  }
+
+  private loadFile(): FileMemoryRecord[] {
+    if (!existsSync(this.config.filePath)) return [];
+    try {
+      const raw = readFileSync(this.config.filePath, "utf8");
+      const parsed: unknown = JSON.parse(raw);
+      if (!Array.isArray(parsed)) {
+        throw new Error(`FileMemoryStore: '${this.config.filePath}' top-level must be an array of memory records.`);
+      }
+      return parsed as FileMemoryRecord[];
+    } catch (err) {
+      throw new Error(`FileMemoryStore: failed to read '${this.config.filePath}': ${(err as Error).message}`);
+    }
+  }
+}

package/examples/onboarding-scaffold/memory.example.json

@@ -0,0 +1,23 @@
+[
+  {
+    "id": "m1",
+    "summary": "Migration runbook for postgres v14 → v15",
+    "detail": "Steps: dump, upgrade binaries, restore. Watch for collation changes affecting indexes. Test against staging before prod.",
+    "created_at": 1748390400,
+    "domain_tags": ["runbook", "postgres", "migration"]
+  },
+  {
+    "id": "m2",
+    "summary": "Incident 2026-05-20: API latency spike traced to N+1 in dashboard query",
+    "detail": "Spike from p99=120ms to 8s. Cause: dashboard query iterating users[].profile without prefetch. Fix: eager-load via select_related. Lesson: lint-check N+1 patterns in dashboard PRs.",
+    "created_at": 1747728000,
+    "domain_tags": ["incident", "performance", "django"]
+  },
+  {
+    "id": "m3",
+    "summary": "Team retro notes 2026-04-15",
+    "detail": "Wins: ship-it-Friday rolled out. Pain: code review backlog grew. Plan: pair-review rotation, async-first sync window 10-11am.",
+    "created_at": 1744675200,
+    "domain_tags": ["retro", "team-process"]
+  }
+]

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

@@ -0,0 +1,117 @@
+// Onboarding scaffold: OpenAI-API-backed LocalModel. v0.7.3.
+//
+// HTTP client to OpenAI's Chat Completions endpoint. Implements the
+// `LocalModel.run(prompt, opts)` typed contract so the v0.7.2 bridge
+// (`LocalModelMcpConnector`) surfaces it as canonical `$ llm prompt=...`
+// for skills.
+//
+// **Prompt-vs-messaging caveat.** `LocalModel.run()` takes a single
+// `prompt` string; Chat Completions expects a list of messages with roles.
+// This adapter wraps the prompt as a single `user` message. Skills that
+// need multi-turn or system-prompt isolation should treat this as a
+// limitation of the v0.7.x contract and pair the LLM dispatch with `$set`
+// + accumulation in the skill body for now. v0.8.x is a likely venue
+// for a richer message-shaped LocalModel contract.
+
+import type {
+  LocalModel,
+  ManifestInfo,
+  StaticCapabilities,
+} from "skillscript-runtime/connectors";
+
+export interface OpenAILocalModelConfig {
+  /** API key. Honor `process.env["OPENAI_API_KEY"]` when undefined. */
+  apiKey?: string;
+  /** Default model. Override per-call via `opts.model`. */
+  defaultModel?: string;
+  /** Override the base URL (for Azure OpenAI, OpenAI-compatible servers, etc.). */
+  baseUrl?: string;
+  /** Request timeout ms. Default 60000. */
+  timeoutMs?: number;
+}
+
+interface ChatCompletionsResponse {
+  choices?: Array<{
+    message?: { content?: string };
+  }>;
+  error?: { message?: string };
+}
+
+export class OpenAILocalModel implements LocalModel {
+  static staticCapabilities(): StaticCapabilities {
+    return {
+      connector_type: "local_model",
+      implementation: "OpenAILocalModel",
+      contract_version: "1.0.0",
+      features: {
+        supports_streaming: false,
+        supports_token_count: false,
+      },
+    };
+  }
+
+  private readonly apiKey: string;
+  private readonly defaultModel: string;
+  private readonly baseUrl: string;
+  private readonly timeoutMs: number;
+
+  constructor(config: OpenAILocalModelConfig = {}) {
+    const apiKey = config.apiKey ?? process.env["OPENAI_API_KEY"];
+    if (apiKey === undefined || apiKey === "") {
+      throw new Error("OpenAILocalModel: OPENAI_API_KEY env var or apiKey config field required.");
+    }
+    this.apiKey = apiKey;
+    this.defaultModel = config.defaultModel ?? "gpt-4o-mini";
+    this.baseUrl = config.baseUrl ?? "https://api.openai.com/v1";
+    this.timeoutMs = config.timeoutMs ?? 60000;
+  }
+
+  async run(prompt: string, opts: { maxTokens?: number; model?: string }): Promise<string> {
+    const model = opts.model ?? this.defaultModel;
+    const body: Record<string, unknown> = {
+      model,
+      messages: [{ role: "user", content: prompt }],
+    };
+    if (opts.maxTokens !== undefined) body["max_tokens"] = opts.maxTokens;
+
+    const controller = new AbortController();
+    const timeoutHandle = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      const resp = await fetch(`${this.baseUrl}/chat/completions`, {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+        signal: controller.signal,
+      });
+      if (!resp.ok) {
+        const text = await resp.text();
+        throw new Error(`OpenAILocalModel: HTTP ${resp.status} — ${text.slice(0, 200)}`);
+      }
+      const json = await resp.json() as ChatCompletionsResponse;
+      if (json.error !== undefined) {
+        throw new Error(`OpenAILocalModel: API error — ${json.error.message ?? "unknown"}`);
+      }
+      const content = json.choices?.[0]?.message?.content;
+      if (typeof content !== "string") {
+        throw new Error("OpenAILocalModel: response missing choices[0].message.content");
+      }
+      return content;
+    } finally {
+      clearTimeout(timeoutHandle);
+    }
+  }
+
+  async manifest(): Promise<ManifestInfo> {
+    return {
+      capabilities_version: "1",
+      manifest: {
+        kind: "openai-local-model",
+        base_url: this.baseUrl,
+        default_model: this.defaultModel,
+      },
+    };
+  }
+}

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

@@ -0,0 +1,110 @@
+// Onboarding scaffold: tmux-shell AgentConnector. v0.7.3.
+//
+// Delivers skill output to a named tmux session via `tmux send-keys`.
+// Matches what nanoclaw-style agent harnesses do internally — adopters
+// with agents running in tmux sessions can wire `# Output: prompt-context:
+// <agent>` end-to-end against this impl.
+//
+// **Scope.** Implements `deliver()` + `list_agents()` + `wake()` +
+// `manifest()` per the v0.7.x AgentConnector contract. `wake()` is a no-op
+// here (tmux panes are always live; wake is for harnesses with sleep modes).
+
+import { spawn } from "node:child_process";
+import type {
+  AgentConnector,
+  AgentDescriptor,
+  AgentStatus,
+  DeliveryPayload,
+  DeliveryReceipt,
+  WakeOpts,
+  WakeReceipt,
+} from "skillscript-runtime/connectors";
+import type { ManifestInfo, StaticCapabilities } from "skillscript-runtime/connectors";
+
+export interface TmuxShellAgentConnectorConfig {
+  /** Map agent ID → tmux session name. Lookup at deliver-time. */
+  sessionMap: Record<string, string>;
+  /** Window index within the session. Default `0`. */
+  windowIndex?: number;
+  /** Pane index within the window. Default `0`. */
+  paneIndex?: number;
+}
+
+export class TmuxShellAgentConnector implements AgentConnector {
+  static staticCapabilities(): StaticCapabilities {
+    return {
+      connector_type: "agent_connector",
+      implementation: "TmuxShellAgentConnector",
+      contract_version: "1.0.0",
+      features: { supports_deliver: true, supports_wake: false },
+    };
+  }
+
+  constructor(private readonly config: TmuxShellAgentConnectorConfig) {}
+
+  async list_agents(): Promise<AgentDescriptor[]> {
+    return Object.keys(this.config.sessionMap).map((agent_id) => ({
+      agent_id,
+      capabilities: ["deliver", "augment", "template"] as const,
+    }));
+  }
+
+  async deliver(agent_id: string, payload: DeliveryPayload): Promise<DeliveryReceipt> {
+    const session = this.config.sessionMap[agent_id];
+    if (session === undefined) {
+      throw new Error(`TmuxShellAgentConnector: no tmux session mapped for agent '${agent_id}'.`);
+    }
+    const winIdx = this.config.windowIndex ?? 0;
+    const paneIdx = this.config.paneIndex ?? 0;
+    const target = `${session}:${winIdx}.${paneIdx}`;
+
+    // Extract the deliverable text. `augment` (prompt-context) carries it
+    // on `content`; `template` carries it on `prompt`.
+    const text = payload.kind === "augment" ? payload.content : payload.prompt;
+    if (text === "") {
+      return { delivered_at: Date.now(), delivery_id: `tmux:${target}:noop` };
+    }
+
+    await this.tmux(["send-keys", "-t", target, "-l", text]);
+    await this.tmux(["send-keys", "-t", target, "Enter"]);
+
+    return {
+      delivered_at: Date.now(),
+      delivery_id: `tmux:${target}:${Date.now()}`,
+    };
+  }
+
+  async wake(agent_id: string, _opts?: WakeOpts): Promise<WakeReceipt> {
+    // tmux panes are always live; no-op wake returns immediately.
+    const session = this.config.sessionMap[agent_id];
+    return {
+      woken_at: Date.now(),
+      ...(session !== undefined ? { session_id: session } : {}),
+    };
+  }
+
+  async agent_status(agent_id: string): Promise<AgentStatus> {
+    return this.config.sessionMap[agent_id] !== undefined ? "active" : "unknown";
+  }
+
+  async manifest(): Promise<ManifestInfo> {
+    return {
+      capabilities_version: "1",
+      manifest: {
+        kind: "tmux-shell-agent-connector",
+        agents_configured: Object.keys(this.config.sessionMap),
+      },
+    };
+  }
+
+  private tmux(args: string[]): Promise<void> {
+    return new Promise((resolve, reject) => {
+      const child = spawn("tmux", args, { stdio: "ignore" });
+      child.on("exit", (code: number | null) => {
+        if (code === 0) resolve();
+        else reject(new Error(`tmux ${args.join(" ")} exited ${code}`));
+      });
+      child.on("error", reject);
+    });
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillscript-runtime",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "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>",