@keystrokehq/cli 0.0.25 → 0.0.26

package/dist/{init-9PiVyCVi.mjs → init-DonAqdBg.mjs}

@@ -45,7 +45,7 @@ function createInitCommand() {
 		description: "Initialize a Keystroke project (creates keystroke.config.ts)",
 		schema: InitOptionsSchema,
 		optionsConfig: INIT_OPTIONS_CONFIG,
-		loadHandler: async () => (await import("./init.handler-Cw-Wg5Fp.mjs")).handleInit
+		loadHandler: async () => (await import("./init.handler-C60qFTIV.mjs")).handleInit
 	});
 }
 //#endregion

package/dist/{init.handler-Cw-Wg5Fp.mjs → init.handler-C60qFTIV.mjs}

@@ -4,7 +4,7 @@ import { D as CliExitError, a as ui, i as fetchLatestNpmPackageVersion } from ".
 import { i as projects } from "./dist-D_KgdxW5.mjs";
 import { a as writeProjectConfig, i as readProjectConfig, r as getProjectConfigPath } from "./project-config-DudGRFPO.mjs";
 import { i as requireClient } from "./context-DHOTSgPb.mjs";
-import { i as UnknownSkillAgentError, n as resolveSkillInstallChoices, r as installKeystrokeAgentSkills, t as summarizeSkillInstall } from "./skill-installer-C-1et32n.mjs";
+import { i as UnknownSkillAgentError, n as resolveSkillInstallChoices, r as installKeystrokeAgentSkills, t as summarizeSkillInstall } from "./skill-installer-AX0X-u1J.mjs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
@@ -13,7 +13,8 @@ import { cancel, isCancel, text } from "@clack/prompts";
 //#region src/lib/keystroke-scaffold-version-ranges.ts
 const WORKFLOW_CORE_PACKAGE_NAME = "@keystrokehq/core";
 const CONFIG_PACKAGE_NAME = "@keystrokehq/config";
-const FALLBACK_WORKFLOW_CORE_VERSION_RANGE = "latest";
+const RUNTIME_PACKAGE_NAME = "@keystrokehq/runtime";
+const FALLBACK_SCAFFOLD_VERSION_RANGE = "latest";
 const DEFAULT_TIMEOUT_MS = 750;
 /**
 * Semver range for scaffold `package.json` — prefers the latest published
@@ -33,6 +34,13 @@ async function configScaffoldVersionRange(options = {}) {
 		readLocalVersion: options.readLocalConfigVersion ?? readLocalConfigVersion
 	});
 }
+async function runtimeScaffoldVersionRange(options = {}) {
+	return packageScaffoldVersionRange({
+		packageName: RUNTIME_PACKAGE_NAME,
+		timeoutMs: options.timeoutMs,
+		readLocalVersion: options.readLocalRuntimeVersion ?? readLocalRuntimeVersion
+	});
+}
 async function packageScaffoldVersionRange(options) {
 	const latestVersion = await fetchLatestNpmPackageVersion({
 		packageName: options.packageName,
@@ -41,7 +49,7 @@ async function packageScaffoldVersionRange(options) {
 	if (latestVersion) return `^${latestVersion}`;
 	const localVersion = options.readLocalVersion();
 	if (localVersion) return `^${localVersion}`;
-	return FALLBACK_WORKFLOW_CORE_VERSION_RANGE;
+	return FALLBACK_SCAFFOLD_VERSION_RANGE;
 }
 function readLocalWorkflowCoreVersion() {
 	try {
@@ -59,6 +67,14 @@ function readLocalConfigVersion() {
 	} catch {}
 	return null;
 }
+function readLocalRuntimeVersion() {
+	try {
+		const raw = readFileSync(createRequire(import.meta.url).resolve(`${RUNTIME_PACKAGE_NAME}/package.json`), "utf-8");
+		const version = JSON.parse(raw).version?.trim();
+		if (version) return version;
+	} catch {}
+	return null;
+}
 //#endregion
 //#region src/commands/init/templates/biome-config.ts
 /**
@@ -210,6 +226,7 @@ function createPackageJsonContent(projectName, options) {
 		},
 		devDependencies: {
 			"@biomejs/biome": "2.4.13",
+			"@keystrokehq/runtime": options.runtimeVersionRange,
 			"@keystrokehq/testing": options.workflowCoreVersionRange,
 			vitest: "^4.0.18",
 			typescript: "^5.9.3"
@@ -312,7 +329,7 @@ async function promptProjectDescription(options) {
 	const t = typeof answer === "string" ? answer.trim() : "";
 	return t.length > 0 ? t : void 0;
 }
-async function ensureScaffoldPackageJson(targetDir, projectName, workflowCoreRange, configRange) {
+async function ensureScaffoldPackageJson(targetDir, projectName, workflowCoreRange, configRange, runtimeRange) {
 	const pkgPath = path.join(targetDir, "package.json");
 	try {
 		const raw = await readFile(pkgPath, "utf-8");
@@ -322,6 +339,7 @@ async function ensureScaffoldPackageJson(targetDir, projectName, workflowCoreRan
 		pkg.dependencies["@keystrokehq/core"] = workflowCoreRange;
 		pkg.dependencies.zod = pkg.dependencies.zod ?? "^4.3.6";
 		pkg.devDependencies = pkg.devDependencies ?? {};
+		pkg.devDependencies["@keystrokehq/runtime"] = runtimeRange;
 		pkg.devDependencies["@keystrokehq/testing"] = workflowCoreRange;
 		pkg.devDependencies.vitest = pkg.devDependencies.vitest ?? "^4.0.18";
 		pkg.devDependencies.typescript = pkg.devDependencies.typescript ?? "^5.9.3";
@@ -331,6 +349,7 @@ async function ensureScaffoldPackageJson(targetDir, projectName, workflowCoreRan
 	} catch {
 		await writeFile(pkgPath, `${createPackageJsonContent(projectName, {
 			configVersionRange: configRange,
+			runtimeVersionRange: runtimeRange,
 			workflowCoreVersionRange: workflowCoreRange
 		})}\n`, "utf-8");
 		return "created";
@@ -408,8 +427,12 @@ async function handleInit(options, ctx) {
 	await projects.track(targetDir, { name: projectName });
 	await installAgentSkillsForInit(targetDir, options);
 	if (options.scaffold) {
-		const [workflowCoreVersionRange, configVersionRange] = await Promise.all([workflowCoreScaffoldVersionRange(), configScaffoldVersionRange()]);
-		await scaffoldProject(targetDir, projectName, workflowCoreVersionRange, configVersionRange);
+		const [workflowCoreVersionRange, configVersionRange, runtimeVersionRange] = await Promise.all([
+			workflowCoreScaffoldVersionRange(),
+			configScaffoldVersionRange(),
+			runtimeScaffoldVersionRange()
+		]);
+		await scaffoldProject(targetDir, projectName, workflowCoreVersionRange, configVersionRange, runtimeVersionRange);
 	}
 }
 /** Write a file only if it does not already exist. Returns true if written. */
@@ -422,9 +445,9 @@ async function writeIfMissing(filePath, content) {
 		return true;
 	}
 }
-async function scaffoldProject(targetDir, projectName, workflowCoreVersionRange, configVersionRange) {
-	const pkgAction = await ensureScaffoldPackageJson(targetDir, projectName, workflowCoreVersionRange, configVersionRange);
-	ui.success(pkgAction === "created" ? `Created package.json (@keystrokehq/core ${workflowCoreVersionRange}, @keystrokehq/config ${configVersionRange})` : `Updated package.json (Keystroke deps -> core ${workflowCoreVersionRange}, config ${configVersionRange})`);
+async function scaffoldProject(targetDir, projectName, workflowCoreVersionRange, configVersionRange, runtimeVersionRange) {
+	const pkgAction = await ensureScaffoldPackageJson(targetDir, projectName, workflowCoreVersionRange, configVersionRange, runtimeVersionRange);
+	ui.success(pkgAction === "created" ? `Created package.json (@keystrokehq/core ${workflowCoreVersionRange}, @keystrokehq/config ${configVersionRange}, @keystrokehq/runtime ${runtimeVersionRange})` : `Updated package.json (Keystroke deps -> core ${workflowCoreVersionRange}, config ${configVersionRange}, runtime ${runtimeVersionRange})`);
 	const files = [
 		{
 			rel: "vitest.config.ts",

package/dist/keystroke.mjs

@@ -521,7 +521,7 @@ const logger = {
 };
 //#endregion
 //#region package.json
-var version = "0.0.25";
+var version = "0.0.26";
 //#endregion
 //#region src/command-registry.ts
 const ROOT_OPTIONS_WITH_VALUES$1 = new Set([
@@ -566,7 +566,7 @@ const lazyCommandDefinitions = [
 	},
 	{
 		name: "init",
-		loadCommand: async () => (await import("./init-9PiVyCVi.mjs")).createInitCommand()
+		loadCommand: async () => (await import("./init-DonAqdBg.mjs")).createInitCommand()
 	},
 	{
 		name: "integrations",
@@ -594,7 +594,7 @@ const lazyCommandDefinitions = [
 	},
 	{
 		name: "skills",
-		loadCommand: async () => (await import("./skills.command-DFpATWrm.mjs")).createSkillsCommand()
+		loadCommand: async () => (await import("./skills.command-B6jly3ew.mjs")).createSkillsCommand()
 	},
 	{
 		name: "sync",

package/dist/{skill-installer-C-1et32n.mjs → skill-installer-AX0X-u1J.mjs}

@@ -4,7 +4,6 @@ import { D as CliExitError, a as ui } from "./keystroke.mjs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { access, cp, mkdir, readFile, readdir, rm, symlink, writeFile } from "node:fs/promises";
-import { fileURLToPath } from "node:url";
 import { autocompleteMultiselect, cancel, isCancel, select } from "@clack/prompts";
 //#region src/lib/skill-installer/package.ts
 const SKILLS_PACKAGE_CONTENT_DIR = "src";
@@ -39,23 +38,14 @@ function normalizeLineEndings$1(value) {
 function normalizeGuidanceBlurb(value) {
 	return `${normalizeLineEndings$1(value).trim()}\n`;
 }
-function resolveMonorepoSkillsBlurbPath() {
-	return fileURLToPath(new URL("../../../../../packages/skills/src/_AGENTS.md", import.meta.url));
-}
-function resolveCliPackageSkillsBlurbPath() {
-	const relativePath = import.meta.url.includes("/dist/") ? "../AGENTS-blurb.md" : "../../../AGENTS-blurb.md";
-	return fileURLToPath(new URL(relativePath, import.meta.url));
-}
 function resolveBundledKeystrokeAgentsBlurbPath() {
 	const require = createRequire(import.meta.url);
 	try {
 		const skillsPackageJsonPath = require.resolve("@keystrokehq/skills/package.json");
 		return path.join(path.dirname(skillsPackageJsonPath), AGENTS_PACKAGE_PATH);
-	} catch {}
-	try {
-		return resolveCliPackageSkillsBlurbPath();
-	} catch {}
-	return resolveMonorepoSkillsBlurbPath();
+	} catch {
+		throw new CliExitError("Could not resolve @keystrokehq/skills. Reinstall the CLI with its bundled skills package.", { exitCode: 1 });
+	}
 }
 async function loadKeystrokeAgentsBlurb() {
 	try {

package/dist/{skills-sync.handler-B_5dgdvs.mjs → skills-sync.handler-DsJP_-XZ.mjs}

@@ -2,7 +2,7 @@
 
 import { D as CliExitError, a as ui } from "./keystroke.mjs";
 import { i as writeJson, r as isJsonMode } from "./output-BWcVRt-T.mjs";
-import { i as UnknownSkillAgentError, n as resolveSkillInstallChoices, r as installKeystrokeAgentSkills, t as summarizeSkillInstall } from "./skill-installer-C-1et32n.mjs";
+import { i as UnknownSkillAgentError, n as resolveSkillInstallChoices, r as installKeystrokeAgentSkills, t as summarizeSkillInstall } from "./skill-installer-AX0X-u1J.mjs";
 import path from "node:path";
 //#region src/commands/skills/skills-sync.handler.ts
 async function handleSkillsSync(options, _ctx) {

package/dist/{skills.command-DFpATWrm.mjs → skills.command-B6jly3ew.mjs}

@@ -38,7 +38,7 @@ function createSkillsCommand() {
 			description: "Install bundled Keystroke skills into selected agent skill directories",
 			schema: SkillsCommandOptionsSchema,
 			optionsConfig: SKILLS_OPTIONS_CONFIG,
-			loadHandler: async () => (await import("./skills-sync.handler-B_5dgdvs.mjs")).handleSkillsSync
+			loadHandler: async () => (await import("./skills-sync.handler-DsJP_-XZ.mjs")).handleSkillsSync
 		})]
 	});
 	cmd.enablePositionalOptions();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keystrokehq/cli",
-  "version": "0.0.25",
+  "version": "0.0.26",
   "private": false,
   "description": "Command-line interface for creating, managing, and deploying Keystroke automations.",
   "type": "module",
@@ -17,7 +17,6 @@
     "keystroke": "./bin/keystroke.mjs"
   },
   "files": [
-    "AGENTS-blurb.md",
     "bin",
     "dist",
     "README.md"
@@ -33,7 +32,7 @@
     "rolldown": "1.0.0",
     "tsx": "^4.21.0",
     "zod": "4.4.3",
-    "@keystrokehq/skills": "0.0.6"
+    "@keystrokehq/skills": "0.0.7"
   },
   "devDependencies": {
     "tsdown": "0.21.10",
@@ -43,15 +42,16 @@
     "@keystroke/local-memory": "0.0.1",
     "@keystroke/shared-types": "0.0.5",
     "@keystrokehq/config": "0.0.2",
+    "@keystroke/test-utils": "0.0.3",
     "@keystroke/typescript-config": "0.0.0",
-    "@keystrokehq/core": "0.0.7",
     "@keystroke/utils": "0.0.0",
+    "@keystrokehq/core": "0.0.7",
+    "@keystrokehq/runtime": "0.0.4",
     "@keystrokehq/workflow-build-contracts": "0.0.3",
-    "@keystroke/workflow-builder": "0.0.7",
-    "@keystroke/workflow-deploy": "0.0.6",
     "@keystrokehq/testing": "0.2.2",
+    "@keystroke/workflow-deploy": "0.0.6",
     "@keystroke/workflow-sdk": "0.0.4",
-    "@keystroke/test-utils": "0.0.3"
+    "@keystroke/workflow-builder": "0.0.7"
   },
   "keywords": [
     "automation",

package/AGENTS-blurb.md

@@ -1,123 +0,0 @@
-# Keystroke Project Context
-
-You are working inside a Keystroke project. Keystroke is a code-first workflow and agent automation platform. Authors define workflows, agents, operations, tasks, triggers, messaging gateways, MCP servers, sandboxes, and credential bindings in TypeScript, then build and deploy them with the Keystroke CLI.
-
-When reasoning about authored code, use this top-level split:
-
-- A `Workflow` is deterministic orchestration. Its `run(...)` method coordinates steps, child workflows, waits, hooks, and agents.
-- An `Agent` is model-driven execution. It runs with agent tools, can use sandboxes, MCP servers, and messaging gateways, and is the right place for llm driven work.
-- A `Task` is the trigger-driven agent path. It combines triggers, a prompt, and an agent run.
-- A workflow can also be registered as an agent tool. Sync workflow tools return inline results; suspending workflow tools yield and resume later; large outputs can return refs inspected with bounded data toolkit tools.
-
-Triggers, tasks, and agent conversations are different entry models:
-
-- a workflow is started by a trigger or direct invocation
-- a trigger is a code-based primitive you author in TypeScript and attach to a workflow
-- a trigger attaches to a workflow and resolves external payload into validated workflow input
-- a trigger is not a chat session; it is an ingress boundary that transforms payload and starts a workflow
-- a task is not attached with `trigger.attach(...)`; it lists triggers inline and resolves a prompt for an agent run
-- an agent conversation is a chat session, not a code-authored primitive like `CronTrigger`, `WebhookTrigger`, or `PollingTrigger`
-- conversations can be started from the UI, from messaging adapters such as Slack, Linear, or GitHub, or from a workflow when the workflow runs an agent
-- messaging gateways configure conversational entry on agents; they are not workflow triggers
-- an agent keeps full context of the conversation session while the workflow side stays replay-safe and stateless between execution boundaries
-
-Keystroke also has one shared unit-of-work primitive: `Operation`.
-
-- `Operation`, `Step`, and `Tool` are aliases for the same class from `@keystrokehq/core`.
-- Use the `Step` name when teaching workflow-side usage.
-- Use the `Tool` name when teaching agent-side usage.
-- Use the `Operation` name when describing shared infrastructure, integrations, or a reusable unit that can be used in both places.
-- The runtime behavior comes from context, not from which alias name was used in the constructor.
-
-Runtime boundary:
-
-- workflows and steps are authored as TypeScript control-flow and unit-of-work code
-- workflows do not run bash commands as part of the workflow authoring model
-- agents are the correct place for bash, filesystem work, and sandbox-managed dependencies such as Python
-
-Keystroke workflow execution is replay-based and stateless at the workflow layer:
-
-- Keystroke does not persist live in-memory workflow state.
-- Instead, it persists execution events and terminal results for execution boundaries, then replays the workflow code from the top with that saved state.
-- The workflow body itself is re-executed during replay. Local variables and control flow are recomputed, not resumed from memory.
-- Because of that, workflow code must be replay-safe and deterministic.
-
-Treat these calls inside `Workflow.run(...)` as execution boundaries:
-
-- `await step.run(...)`
-- `await operation.run(...)`
-- `await childWorkflow.run(...)`
-- `await agent.run(...)`
-
-What gets persisted:
-
-- For steps, Keystroke persists created/completed/failed state and reuses the saved result during workflow replay.
-- For child workflows, Keystroke persists the child run and its terminal result, then resumes the parent workflow with that saved outcome.
-- For agents, Keystroke persists agent execution state and terminal output, then resumes the workflow with that saved result.
-- The workflow's own in-memory logic is not persisted. The platform saves boundary state, not the live workflow stack.
-
-Where code runs:
-
-- Operations used as workflow steps are low-level units of work and run in separate worker executions.
-- Child workflows run as separate workflow executions in their own workers, using the same replay model as parent workflows.
-- Agents run outside the workflow replay worker. They run in persisted sandboxes with a persistent filesystem, where they can use files, shell commands, installed skills, MCP servers, and other runtime tools. The filesystem persists over all agent runs for a deployed agent.
-- Operations used as agent tools are not top-level orchestration units. A tool runs inside the agent runtime when the agent chooses to call it, inside that persisted sandbox context.
-
-Workflow triggers versus agent conversations:
-
-- use code-authored triggers when external schedules, webhook requests, or polling results should become workflow input
-- use agent conversations when a user or system is chatting with an agent over time
-- author triggers in code; do not think of conversations as authored primitives in the same way
-- messaging adapters normalize inbound events into thread-based conversations, and the agent responds inside that conversation context
-- a workflow can still start an agent-backed conversation by running an agent, but that is different from a workflow trigger boundary
-
-Authoring implications:
-
-- Put orchestration, branching, loops, waits, and composition in workflows.
-- Put deterministic side effects and integration calls in operations used as steps.
-- Put LLM-driven reasoning and tool selection in agents.
-- Put concrete callable actions in operations used as tools.
-- Use `largeResultMode: 'ref'` plus `describe_ref`, `read_ref`, and `slice_ref` for large workflow-tool outputs. Reducers and DuckDB-backed data tools are deferred.
-- Use `midSessionSnapshot: true` only for measured workflow-tool cases that need Phase D replay. Current snapshot behavior is conversation-log replay, not native Pi process restore.
-- Do not depend on workflow-local mutable state, random values, direct network I/O, or filesystem mutations in the workflow body itself unless they happen behind a Keystroke execution boundary.
-- Never assume workflow-local memory or filesystem state survives between replays. If state must survive, return it from an operation, agent, or child workflow, or persist it externally.
-
-## Workflow Builder File Structure
-
-The workflow builder now relies on explicit file structure. Teach and author Keystroke code with one exported primitive per typed file:
-
-- `*.workflow.ts` for one `Workflow`
-- `*.step.ts`, `*.tool.ts`, or `*.operation.ts` for one exported `Operation`
-- `*.agent.ts` for one `Agent`
-- `*.gateway.ts` for one `MessagingGateway`
-- `*.trigger.ts` for one trigger
-- `*.credential-set.ts` for one `CredentialSet`
-- `*.mcp-server.ts` for one `McpServer`
-
-Builder note:
-
-- `*.step.ts`, `*.tool.ts`, and `*.operation.ts` all validate as the same operation convention
-- choose the suffix that communicates intent to the reader
-
-Required structure:
-
-- exported primitives should be top-level and statically visible
-- helper files such as `schemas.ts`, `utils.ts`, or `prompts.ts` should not export primitives
-- a `*.trigger.ts` file may also export that trigger's `TriggerAttachment` values
-- tests are exempt, but authored project code should follow the typed-file convention everywhere
-
-Example layout:
-
-```text
-customer-support/
-  crm-api.credential-set.ts
-  lookup-customer.tool.ts
-  support.agent.ts
-  support.gateway.ts
-  triage.step.ts
-  support.workflow.ts
-  support.trigger.ts
-  coding.sandbox.ts
-  docs.mcp-server.ts
-  schemas.ts
-```