external-subagent 0.4.0 → 0.4.1

package/README.md

@@ -91,6 +91,52 @@ stale or missing binaries) and `postpack` runs the static tarball checks. A
 development checkout packs the same way (`npm pack` after `cargo` is
 available); see [docs/operations.md](docs/operations.md) for release checks.
 
+## Spawn profiles
+
+A spawn profile is a named JSON preset for the spawn inputs, stored as one
+JSON file per profile in the `profiles/` directory next to `config.json`
+(`~/Library/Application Support/external-subagent/profiles/` by default;
+`profile list` reports the exact path in use). Every `*.json` file in the
+directory is discovered by its `name` field; the same name defined in two
+files is rejected, and invalid files are reported as warnings and excluded
+from the available set.
+
+```json
+{
+  "name": "codex-yolo",
+  "subagent": "codex",
+  "model": "gpt-5",
+  "permission_mode": "yolo",
+  "developer_instructions": "Always reply in English."
+}
+```
+
+| Field | Meaning |
+|---|---|
+| `name` | Required, unique across files; trimmed, non-empty, at most 128 bytes |
+| `subagent` | `zcode`, `dsh`, `codex`, or `agy` |
+| `model` | Model token, named per target: `dsh` wants `provider:model`, `zcode` accepts `provider/model` or a bare token, `codex` and `agy` take a bare slug |
+| `effort` | Effort token; some runtime models require one (for example `agy` rejects `gemini-3.8-flash` without `--effort`) and the spawn error surfaces the runtime's message verbatim |
+| `permission_mode` | `build`, `edit`, `plan`, or `yolo`; defaults to `build` when unset |
+| `developer_instructions` | Free-form instructions, delivered as described below |
+
+`--profile` cannot be combined with `--subagent`, `--model`, `--effort`, or
+`--permission_mode`; put those in the profile JSON or omit `profile`. Fields
+left out of the profile fall back to the same defaults as an unprofiled
+spawn. `developer_instructions` rides the codex runtime's native
+`developerInstructions` channel when the effective subagent is `codex`; every
+other subagent receives it silently concatenated in front of the prompt:
+
+```
+Developer Instructions: {developer_instructions}
+----------
+{prompt}
+```
+
+Inspect what is loaded with `external-subagent profile list` and
+`external-subagent profile show <name>`; an empty `profile list` result
+carries a `hint` field with this format summary.
+
 ## Publishing
 
 Releases publish from CI via npm Trusted Publishing (OIDC): pushing a `vX.Y.Z`

package/cli/commands/tasks.mjs

@@ -499,6 +499,13 @@ export function parseProfileArgs(args) {
   throw new CliError('INVALID_ARGUMENT', `unsupported profile operation: ${operation}`, 2);
 }
 
+// Attached to `profile list` only when no usable profile exists, so a fresh
+// installation sees the format reference instead of an unexplained empty list.
+const EMPTY_PROFILES_HINT = 'no profiles found; create one JSON file per profile in this directory, '
+  + 'e.g. {"name":"codex-yolo","subagent":"codex","model":"gpt-5","permission_mode":"yolo"}; '
+  + 'fields: name (required), subagent, model, effort, permission_mode (build|edit|plan|yolo), '
+  + 'developer_instructions; see the "Spawn profiles" section of README.md';
+
 export function profileCommand(paths, inputOrArgs, env = process.env) {
   const input = Array.isArray(inputOrArgs) ? parseProfileArgs(inputOrArgs) : inputOrArgs;
   if (!input || typeof input !== 'object' || Array.isArray(input)) {
@@ -526,6 +533,7 @@ export function profileCommand(paths, inputOrArgs, env = process.env) {
         profiles: [],
         warnings: [],
         message: `profiles directory does not exist: ${dir}`,
+        hint: EMPTY_PROFILES_HINT,
       };
     }
     return {
@@ -533,6 +541,7 @@ export function profileCommand(paths, inputOrArgs, env = process.env) {
       directory: dir,
       profiles: scanned.availableNames,
       warnings: scanned.warnings.map((w) => ({ file: w.file, diagnostic: w.diagnostic })),
+      ...(scanned.availableNames.length === 0 ? { hint: EMPTY_PROFILES_HINT } : {}),
     };
   }
 

package/cli/constants.mjs

@@ -8,7 +8,7 @@ const IS_DEBUG_VARIANT = process.env.EXTERNAL_SUBAGENT_VARIANT === 'debug';
 
 export const PRODUCT_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debug' : 'external-subagent';
 export const PRODUCT_ID = IS_DEBUG_VARIANT ? 'external_subagent_debug' : 'external_subagent';
-export const VERSION = '0.4.0';
+export const VERSION = '0.4.1';
 export const LAUNCH_AGENT_LABEL = IS_DEBUG_VARIANT ? 'com.external-subagent-debug.daemon' : 'com.external-subagent.daemon';
 export const DAEMON_BIN_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debugd' : 'external-subagentd';
 export const MCP_BIN_NAME = IS_DEBUG_VARIANT ? 'external-subagent-debug-mcp' : 'external-subagent-mcp';

package/npm/native/darwin-arm64/payload.json

@@ -1,20 +1,20 @@
 {
   "schema_version": 1,
   "product": "external-subagent",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "platform": "darwin-arm64",
   "files": [
     {
       "name": "external-subagentd",
-      "bytes": 10115152,
+      "bytes": 10116128,
       "mode": "755",
-      "sha256": "2fbb31359c60e4834f3ad90733c03942cafe5fd8ab1bc5f2f9512128a8746237"
+      "sha256": "9c650b9c096f4060e927eced4d05665749123177e3c7d105a13a8a466633ed77"
     },
     {
       "name": "external-subagent-mcp",
       "bytes": 935888,
       "mode": "755",
-      "sha256": "73fc786b07873983fb347af756cc316cebb071a14380442777c27c3928e6f2ec"
+      "sha256": "e519c71451bc27bf217316c57fe92d82e8e8fc546c13194455ad60dbc0cdc9f7"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "external-subagent",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Manage bounded ZCode, DeepSeek Harness (DSH), Codex, and Google Antigravity (agy) subagent tasks through a local MCP service for any local host (Codex, ZCode, or a custom MCP client)",
   "type": "module",
   "license": "MIT",