tweaks

sanchitrk · Sep 17, 2026 · Sep 15, 2026 · Sep 15, 2026 · Sep 16, 2026 · Sep 16, 2026
commit 0ee433a27caad28a6194708b894a5ef8cafaac71
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,21 +11,6 @@ This file is the canonical source for unreleased changes and published release n
 
 ## [Unreleased]
 
-### Breaking Changes
-
-- A settings file that exists and cannot be used now fails instead of being skipped with a warning: unreadable, unparseable and invalid files fail `Harness.layer` construction, and an edit that breaks one fails the next exchange. `Settings.Service.load` gains a `SettingsError` error channel, which reaches clients as the `settings` failure category carrying the path, reason and offending key, and the CLI renders the same. A missing file is still ordinary.
-
-- A plugin entry is either a **module** or a **configuration object**, and the `"!id"` disable syntax is gone. A module is a definition, a path, a `file:` URL, or a package spec; it is loaded and takes the position it is written at. A configuration object is `{ "plugin": "<id>" }` or `{ "package": "<name>" }` plus `enabled`/`options`; it never loads, installs or reorders anything, and a name matching nothing in the selection is ignored rather than failing the boot.
-- A bare string is a module only, so a built-in is no longer selected by ID. A settings file addresses built-ins through `{ "plugin": "codework.tool.bash", … }`, and an embedder composing its own order passes its whole selection, prompt plugin included.
-- `Plugin.setup` takes the plugin's configuration block as a second argument, `setup(ctx, options)`.
-- A configuration entry naming both `plugin` and `package`, naming neither, or carrying a non-boolean `enabled` or an `options` that is not a plain record, now fails plugin preparation. Settings files were already rejected at decode; this closes the same hole for `Harness.layer({ plugins })`.
-
-### Added
-
-- Plugin entries accept an `options` block in `settings.json` and in `Harness.layer({ plugins })`, handed to that plugin's `setup`. The block is opaque, so a `null` inside it reaches the plugin instead of being dropped the way a `null` elsewhere in a settings file is.
-- A configuration entry can name a plugin by the package it came from — its package name, its spec, the path it was loaded from, or the name a local package's manifest declares — so `{ "package": "@acme/codework-tool-proc", "enabled": false }` works without knowing the plugin's ID.
-- Example plugins under `extras/`: `@acme/codework-tool-proc` (a tool package), `codework-prompt-life` (a prompt package), and two single-file plugins in `extras/plugins/`.
-
 ## [@codeworksh/aikit@0.8.0]
 
 ### Added

diff --git a/extras/codework-prompt-life/README.md b/extras/codework-prompt-life/README.md
@@ -1,16 +1,16 @@
-# codework-prompt-life
+# @acme/codework-prompt-life
 
 An example third-party **prompt plugin**: it appends a short section on the meaning of life to
 the system prompt.
 
-The package name is deliberately unscoped, so it shows the other spelling a settings entry can
-take — `codework-prompt-life` alongside `@acme/codework-tool-proc`.
+The package uses the example `@acme` namespace to demonstrate how a third-party scoped plugin is
+loaded and then configured by package name.
 
 ## Using it
 
 ```jsonc
 {
-	"plugins": ["codework-prompt-life", { "package": "codework-prompt-life", "options": { "answer": 42 } }],
+	"plugins": ["@acme/codework-prompt-life", { "package": "@acme/codework-prompt-life", "options": { "answer": 42 } }],
 }
 ```
 

diff --git a/extras/codework-prompt-life/package.json b/extras/codework-prompt-life/package.json
@@ -1,5 +1,5 @@
 {
-	"name": "codework-prompt-life",
+	"name": "@acme/codework-prompt-life",
 	"version": "0.0.0",
 	"private": true,
 	"description": "Example third-party codework plugin: a prompt section on the meaning of life.",

diff --git a/extras/codework-prompt-life/src/index.ts b/extras/codework-prompt-life/src/index.ts
@@ -3,8 +3,8 @@
  * whatever an earlier one set, so it belongs *after* the tool plugins and prompt plugins it
  * builds on — `ctx.plugin.prompt.get()` sees only contributions made before it ran:
  *
- *   { "plugins": ["codework-prompt-life",
- *                 { "package": "codework-prompt-life", "options": { "answer": 42 } }] }
+ *   { "plugins": ["@acme/codework-prompt-life",
+ *                 { "package": "@acme/codework-prompt-life", "options": { "answer": 42 } }] }
  */
 import { Plugin } from "@codeworksh/harness/effect";
 

diff --git a/extras/plugins/package.json b/extras/plugins/package.json
@@ -1,5 +1,5 @@
 {
-	"name": "codework-local-plugins",
+	"name": "@acme/codework-local-plugins",
 	"version": "0.0.0",
 	"private": true,
 	"description": "Example single-file codework plugins, loaded by path rather than installed.",

diff --git a/package.json b/package.json
@@ -38,12 +38,12 @@
 		"release:harness:dry": "pnpm --filter @codeworksh/harness run release:dry"
 	},
 	"devDependencies": {
+		"@acme/codework-local-plugins": "workspace:*",
+		"@acme/codework-prompt-life": "workspace:*",
 		"@acme/codework-sandbox-vercel": "workspace:*",
 		"@acme/codework-tool-proc": "workspace:*",
 		"@effect/tsgo": "catalog:",
 		"@types/node": "catalog:",
-		"codework-local-plugins": "workspace:*",
-		"codework-prompt-life": "workspace:*",
 		"typescript": "catalog:",
 		"vite-plus": "catalog:"
 	},

diff --git a/packages/harness/README.md b/packages/harness/README.md
@@ -121,7 +121,7 @@ Settings entries take the same two forms, and they extend the built-in selection
 // codework.json, ~/.codework/settings.json, or a --user-config-dir
 {
 	"plugins": [
-		"codework-prompt-life",
+		"@acme/codework-prompt-life",
 		"@acme/codework-tool-proc@1.2.0",
 		"./plugins/local.ts",
 		{ "package": "@acme/codework-tool-proc", "options": { "limit": 20 } },

diff --git a/packages/harness/src/effect/harness.ts b/packages/harness/src/effect/harness.ts
@@ -6,7 +6,7 @@ import { Event } from "../event/event.ts";
 import { Global } from "../global.ts";
 import { EventRegistry } from "../event/registry.ts";
 import { prepare, type PluginRef } from "../plugin/catalog.ts";
-import { builtins } from "../plugin/internal.ts";
+import { builtins } from "../plugin/builtin.ts";
 import { RunnerExecute } from "../runner/execute.ts";
 import { LLM } from "../runner/llm.ts";
 import { Loop } from "../runner/loop.ts";

diff --git a/packages/harness/src/plugin/internal.ts → packages/harness/src/plugin/builtin.ts b/packages/harness/src/plugin/internal.ts → packages/harness/src/plugin/builtin.ts
@@ -1,5 +1,5 @@
-import { defaultPromptPlugin } from "./internal/prompt/default.ts";
-import { bashPlugin } from "./internal/tool/bash.ts";
+import { defaultPromptPlugin } from "./builtin/prompt/default.ts";
+import { bashPlugin } from "./builtin/tool/bash.ts";
 
 /**
  * Every plugin the harness ships, and the selection a caller who passes no `plugins` gets. Tool

diff --git a/...ess/src/plugin/internal/prompt/default.ts → ...ness/src/plugin/builtin/prompt/default.ts b/...ess/src/plugin/internal/prompt/default.ts → ...ness/src/plugin/builtin/prompt/default.ts
diff --git a/.../harness/src/plugin/internal/tool/bash.ts → ...s/harness/src/plugin/builtin/tool/bash.ts b/.../harness/src/plugin/internal/tool/bash.ts → ...s/harness/src/plugin/builtin/tool/bash.ts
diff --git a/packages/harness/test/fixtures/bash.spec.ts b/packages/harness/test/fixtures/bash.spec.ts
@@ -8,8 +8,8 @@ import { Harness } from "../../src/effect/harness.ts";
 import { Sandbox } from "../../src/effect/sandbox.ts";
 import { Session } from "../../src/effect/session.ts";
 import type { SandboxDriver } from "../../src/sandbox/driver.ts";
-import { bashPlugin } from "../../src/plugin/internal/tool/bash.ts";
-import { defaultPromptPlugin } from "../../src/plugin/internal/prompt/default.ts";
+import { bashPlugin } from "../../src/plugin/builtin/tool/bash.ts";
+import { defaultPromptPlugin } from "../../src/plugin/builtin/prompt/default.ts";
 import { pendingCall } from "../tools.fixture.ts";
 import { toolTurn } from "./llm.ts";
 import { remoteSuite } from "./live.ts";

diff --git a/packages/harness/test/fixtures/runner.cycle.spec.ts b/packages/harness/test/fixtures/runner.cycle.spec.ts
@@ -25,7 +25,7 @@ import { SessionLive } from "../../src/session/live.ts";
 import { SessionRuntime } from "../../src/session/runtime.ts";
 import type { SessionSchema } from "../../src/session/schema.ts";
 import { Session } from "../../src/session/session.ts";
-import { builtins } from "../../src/plugin/internal.ts";
+import { builtins } from "../../src/plugin/builtin.ts";
 import { State } from "../../src/state/state.ts";
 
 const database = Database.layer(":memory:");

diff --git a/packages/harness/test/fixtures/tools.registry.vercel.spec.ts b/packages/harness/test/fixtures/tools.registry.vercel.spec.ts
@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { afterAll, beforeAll, describe, expect, it } from "vite-plus/test";
 import { SandboxInstance } from "../../src/sandbox/instance.ts";
 import * as EnvVercel from "../../src/sandboxes/vercel/provider.ts";
-import { bashTool } from "../../src/plugin/internal/tool/bash.ts";
+import { bashTool } from "../../src/plugin/builtin/tool/bash.ts";
 import * as Registry from "../../src/tool/registry.ts";
 import { fromSandboxShell, ToolShell } from "../../src/tool/shell.ts";
 import * as Tool from "../../src/tool/tool.ts";

diff --git a/packages/harness/test/plugin.examples.test.ts b/packages/harness/test/plugin.examples.test.ts
@@ -7,8 +7,8 @@ import { describe, expect, it } from "vite-plus/test";
 import { Harness } from "../src/effect/harness.ts";
 import { Session } from "../src/effect/session.ts";
 import type { PluginRef } from "../src/plugin/catalog.ts";
-import { defaultPromptPlugin } from "../src/plugin/internal/prompt/default.ts";
-import { bashPlugin } from "../src/plugin/internal/tool/bash.ts";
+import { defaultPromptPlugin } from "../src/plugin/builtin/prompt/default.ts";
+import { bashPlugin } from "../src/plugin/builtin/tool/bash.ts";
 import { immediateOpen, toolTurn } from "./fixtures/llm.ts";
 import { withSettings } from "./fixtures/settings.ts";
 import { pendingCall } from "./tools.fixture.ts";
@@ -53,7 +53,7 @@ const selection: ReadonlyArray<PluginRef> = [
 	defaultPromptPlugin,
 	example("codework-prompt-life"),
 	// The README's second line: configure by the package name, not the path it was loaded from.
-	{ package: "codework-prompt-life", options: { answer: 43 } },
+	{ package: "@acme/codework-prompt-life", options: { answer: 43 } },
 	example("plugins/house-style.ts"),
 	{ package: example("plugins/house-style.ts"), options: { rules: ["No `any` in TypeScript."] } },
 ];

diff --git a/packages/harness/test/plugin.external.test.ts b/packages/harness/test/plugin.external.test.ts
@@ -10,13 +10,13 @@ import { Session } from "../src/effect/session.ts";
 import { Event } from "../src/event/event.ts";
 import { EventSchema } from "../src/event/schema.ts";
 import { prepare, type PluginRef } from "../src/plugin/catalog.ts";
-import { builtins } from "../src/plugin/internal.ts";
+import { builtins } from "../src/plugin/builtin.ts";
 import { fallback } from "../src/plugin/prompt/registry.ts";
 import { Settings } from "../src/settings/settings.ts";
 import type { LLM } from "../src/runner/llm.ts";
 import { SessionSchema } from "../src/session/schema.ts";
-import { bashPlugin } from "../src/plugin/internal/tool/bash.ts";
-import { defaultPromptPlugin } from "../src/plugin/internal/prompt/default.ts";
+import { bashPlugin } from "../src/plugin/builtin/tool/bash.ts";
+import { defaultPromptPlugin } from "../src/plugin/builtin/prompt/default.ts";
 import { immediateOpen, toolTurn } from "./fixtures/llm.ts";
 import { withSettings } from "./fixtures/settings.ts";
 import { pendingCall } from "./tools.fixture.ts";

diff --git a/packages/harness/test/plugin.host.test.ts b/packages/harness/test/plugin.host.test.ts
@@ -9,7 +9,7 @@ import type { SharedPluginContext } from "../src/plugin/context.ts";
 import { fallback } from "../src/plugin/prompt/registry.ts";
 import { make } from "../src/plugin/registry.ts";
 import * as Tool from "../src/tool/tool.ts";
-import { defaultPromptPlugin } from "../src/plugin/internal/prompt/default.ts";
+import { defaultPromptPlugin } from "../src/plugin/builtin/prompt/default.ts";
 import { pendingCall } from "./tools.fixture.ts";
 import { assistant, immediateOpen } from "./fixtures/llm.ts";
 import { withSettings } from "./fixtures/settings.ts";

diff --git a/packages/harness/test/plugin.prompt.test.ts b/packages/harness/test/plugin.prompt.test.ts
@@ -5,7 +5,7 @@ import { realpath } from "node:fs/promises";
 import { join } from "node:path";
 import { Harness } from "../src/effect/harness.ts";
 import { Session } from "../src/effect/session.ts";
-import { defaultPromptPlugin } from "../src/plugin/internal/prompt/default.ts";
+import { defaultPromptPlugin } from "../src/plugin/builtin/prompt/default.ts";
 import { immediateOpen } from "./fixtures/llm.ts";
 import { withSettings } from "./fixtures/settings.ts";
 

diff --git a/packages/harness/test/runner.loop.test.ts b/packages/harness/test/runner.loop.test.ts
@@ -1,6 +1,6 @@
 import "./utils/env.ts";
 import type { Plugin } from "../src/plugin/plugin.ts";
-import { builtins as plugins } from "../src/plugin/internal.ts";
+import { builtins as plugins } from "../src/plugin/builtin.ts";
 import { Settings } from "../src/settings/settings.ts";
 import { createAssistantMessageEventStream, Message } from "@codeworksh/aikit";
 import { Cause, DateTime, Deferred, Effect, Exit, Fiber, Layer, Option, Schema } from "effect";

diff --git a/packages/harness/test/scripts/codework-sandbox-vercel-smoke.mjs b/packages/harness/test/scripts/codework-sandbox-vercel-smoke.mjs
@@ -1,7 +1,7 @@
 import dedent from "dedent";
 import { existsSync } from "node:fs";
 import { spawn } from "node:child_process";
-import { mkdir, mkdtemp, readdir, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -11,6 +11,9 @@ const harness = resolve(root, "packages/harness");
 const external = resolve(root, "extras/codework-sandbox-vercel");
 const envFile = resolve(harness, ".env.local");
 if (existsSync(envFile)) process.loadEnvFile(envFile);
+const manifest = JSON.parse(await readFile(resolve(harness, "package.json"), "utf8"));
+const effectVersion = manifest.dependencies?.effect;
+if (typeof effectVersion !== "string") throw new Error("harness package.json must declare an Effect dependency");
 
 const temporary = await mkdtemp(resolve(tmpdir(), "codework-sandbox-package-"));
 const artifacts = resolve(temporary, "artifacts");
@@ -53,7 +56,7 @@ try {
 				dependencies: {
 					"@codeworksh/harness": `file:${harnessTarball}`,
 					"@acme/codework-sandbox-vercel": `file:${externalTarball}`,
-					effect: "4.0.0-beta.107",
+					effect: effectVersion,
 				},
 			},
 			null,

diff --git a/packages/harness/test/settings.loop.test.ts b/packages/harness/test/settings.loop.test.ts
@@ -12,7 +12,7 @@ import { EventList } from "../src/event/list.ts";
 import { LLM } from "../src/runner/llm.ts";
 import { defaults } from "../src/settings/schema.ts";
 import * as Tool from "../src/tool/tool.ts";
-import { defaultPromptPlugin } from "../src/plugin/internal/prompt/default.ts";
+import { defaultPromptPlugin } from "../src/plugin/builtin/prompt/default.ts";
 import { assistant } from "./fixtures/llm.ts";
 import { withSettings } from "./fixtures/settings.ts";
 

diff --git a/packages/harness/test/tools.bash.test.ts b/packages/harness/test/tools.bash.test.ts
@@ -2,7 +2,7 @@ import { Effect, Exit, Layer, Stream } from "effect";
 import { describe, expect, it } from "vite-plus/test";
 import { Sandbox } from "../src/sandbox/sandbox.ts";
 import { type ExecChunk, fromExec, Shell as SandboxShell } from "../src/sandbox/shell/shell.ts";
-import { bashTool } from "../src/plugin/internal/tool/bash.ts";
+import { bashTool } from "../src/plugin/builtin/tool/bash.ts";
 import * as Executor from "../src/tool/executor.ts";
 import { make as makeProgress, noop as progressNoop } from "../src/tool/progress.ts";
 import * as Tool from "../src/tool/tool.ts";

diff --git a/packages/harness/test/tools.local.shell.test.ts b/packages/harness/test/tools.local.shell.test.ts
@@ -4,7 +4,7 @@ import path from "node:path";
 import { describe, expect, it } from "vite-plus/test";
 import { Sandbox } from "../src/sandbox/sandbox.ts";
 import { type ExecChunk, Shell } from "../src/sandbox/shell/shell.ts";
-import { bashTool } from "../src/plugin/internal/tool/bash.ts";
+import { bashTool } from "../src/plugin/builtin/tool/bash.ts";
 import * as Executor from "../src/tool/executor.ts";
 import { noop as progressNoop } from "../src/tool/progress.ts";
 import { fromSandboxShell, local, ToolShell, ToolShellTimeout } from "../src/tool/shell.ts";

diff --git a/packages/harness/test/tools.registry.remote.e2e.test.ts b/packages/harness/test/tools.registry.remote.e2e.test.ts
@@ -7,7 +7,7 @@ import { join } from "node:path";
 import { afterAll, beforeAll, expect, it } from "vite-plus/test";
 import * as EnvDaytona from "../src/sandboxes/daytona/provider.ts";
 import { SandboxInstance } from "../src/sandbox/instance.ts";
-import { bashTool } from "../src/plugin/internal/tool/bash.ts";
+import { bashTool } from "../src/plugin/builtin/tool/bash.ts";
 import * as Registry from "../src/tool/registry.ts";
 import { fromSandboxShell, ToolShell } from "../src/tool/shell.ts";
 import * as Tool from "../src/tool/tool.ts";

diff --git a/packages/harness/test/tools.registry.test.ts b/packages/harness/test/tools.registry.test.ts
@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { describe, expect, it } from "vite-plus/test";
 import { Sandbox } from "../src/sandbox/sandbox.ts";
 import { type ExecChunk, fromExec, type ISandboxExe, Shell as SandboxShell } from "../src/sandbox/shell/shell.ts";
-import { bashTool } from "../src/plugin/internal/tool/bash.ts";
+import { bashTool } from "../src/plugin/builtin/tool/bash.ts";
 import * as Executor from "../src/tool/executor.ts";
 import { ToolProgress } from "../src/tool/progress.ts";
 import * as Registry from "../src/tool/registry.ts";

diff --git a/packages/harness/test/tools.tool.test.ts b/packages/harness/test/tools.tool.test.ts
@@ -1,6 +1,6 @@
 import { Effect, Schema } from "effect";
 import { describe, expect, it } from "vite-plus/test";
-import { bashDef } from "../src/plugin/internal/tool/bash.ts";
+import { bashDef } from "../src/plugin/builtin/tool/bash.ts";
 import * as Executor from "../src/tool/executor.ts";
 import * as Tool from "../src/tool/tool.ts";
 import { pendingCall } from "./tools.fixture.ts";

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml