@agent-relay/sdk 6.0.10 → 6.0.11

package/dist/examples/persona-spawn.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=persona-spawn.d.ts.map

package/dist/examples/persona-spawn.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"persona-spawn.d.ts","sourceRoot":"","sources":["../../src/examples/persona-spawn.ts"],"names":[],"mappings":""}

package/dist/examples/persona-spawn.js

@@ -0,0 +1,44 @@
+/**
+ * persona-spawn — spawn an agent from an AgentWorkforce persona.
+ *
+ * Personas are JSON files describing a pre-configured agent (harness, model,
+ * system prompt, MCP servers, permissions). They live in
+ *   ./agentworkforce/personas
+ * or any directory you pass via `searchDirs` / `extraDirs`.
+ *
+ * Run:
+ *   npm run build && node dist/examples/persona-spawn.js frontend "Build a settings page"
+ *
+ * Environment:
+ *   RELAY_API_KEY — Relaycast workspace key (required)
+ */
+import { AgentRelay } from "../relay.js";
+import { listPersonas } from "../personas.js";
+const [, , personaId, ...taskParts] = process.argv;
+const task = taskParts.join(" ").trim();
+if (!personaId) {
+    const found = listPersonas();
+    console.error("Usage: persona-spawn <personaId> [task...]\n");
+    if (found.length > 0) {
+        console.error("Personas discovered in the default cascade:");
+        for (const p of found) {
+            console.error(`  - ${p.id}  (${p.path})`);
+        }
+    }
+    else {
+        console.error("No personas found. Place JSON files under ./agentworkforce/personas " +
+            "or set AGENT_WORKFORCE_HOME.");
+    }
+    process.exit(1);
+}
+const relay = new AgentRelay();
+relay.onAgentSpawned = (agent) => console.log(`spawned ${agent.name} (${agent.runtime})`);
+relay.onAgentExited = (agent) => console.log(`exited ${agent.name} code=${agent.exitCode ?? "none"}`);
+const agent = await relay.spawnPersona(personaId, {
+    ...(task ? { task } : {}),
+    channels: ["general"],
+});
+console.log(`agent ${agent.name} ready, waiting for exit...`);
+await agent.waitForExit();
+await relay.shutdown();
+//# sourceMappingURL=persona-spawn.js.map

package/dist/examples/persona-spawn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"persona-spawn.js","sourceRoot":"","sources":["../../src/examples/persona-spawn.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,MAAM,CAAC,EAAE,AAAD,EAAG,SAAS,EAAE,GAAG,SAAS,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;AACnD,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;AAExC,IAAI,CAAC,SAAS,EAAE,CAAC;IACf,MAAM,KAAK,GAAG,YAAY,EAAE,CAAC;IAC7B,OAAO,CAAC,KAAK,CAAC,8CAA8C,CAAC,CAAC;IAC9D,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,OAAO,CAAC,KAAK,CAAC,6CAA6C,CAAC,CAAC;QAC7D,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;SAAM,CAAC;QACN,OAAO,CAAC,KAAK,CACX,sEAAsE;YACpE,8BAA8B,CACjC,CAAC;IACJ,CAAC;IACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,KAAK,GAAG,IAAI,UAAU,EAAE,CAAC;AAE/B,KAAK,CAAC,cAAc,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC;AAC1F,KAAK,CAAC,aAAa,GAAG,CAAC,KAAK,EAAE,EAAE,CAC9B,OAAO,CAAC,GAAG,CAAC,UAAU,KAAK,CAAC,IAAI,SAAS,KAAK,CAAC,QAAQ,IAAI,MAAM,EAAE,CAAC,CAAC;AAEvE,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE;IAChD,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACzB,QAAQ,EAAE,CAAC,SAAS,CAAC;CACtB,CAAC,CAAC;AAEH,OAAO,CAAC,GAAG,CAAC,SAAS,KAAK,CAAC,IAAI,6BAA6B,CAAC,CAAC;AAC9D,MAAM,KAAK,CAAC,WAAW,EAAE,CAAC;AAC1B,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAC"}

package/dist/index.d.ts

@@ -15,4 +15,5 @@ export * from './workflows/index.js';
 export * from './spawn-from-env.js';
 export * from './cli-registry.js';
 export * from './cli-resolver.js';
+export * from './personas.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACvG,OAAO,EACL,gBAAgB,EAChB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AACrB,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACpE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACtE,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACvG,OAAO,EACL,gBAAgB,EAChB,KAAK,wBAAwB,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,sBAAsB,EAC3B,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AACrB,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AACpE,YAAY,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACtE,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC"}

package/dist/index.js

@@ -14,4 +14,5 @@ export * from './workflows/index.js';
 export * from './spawn-from-env.js';
 export * from './cli-registry.js';
 export * from './cli-resolver.js';
+export * from './personas.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,eAAe,EAA+B,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACvG,OAAO,EACL,gBAAgB,GAKjB,MAAM,aAAa,CAAC;AACrB,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEpE,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,eAAe,EAA+B,uBAAuB,EAAE,MAAM,gBAAgB,CAAC;AACvG,OAAO,EACL,gBAAgB,GAKjB,MAAM,aAAa,CAAC;AACrB,cAAc,aAAa,CAAC;AAC5B,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEpE,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC"}

package/dist/personas.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Persona loading and translation.
+ *
+ * A persona is a JSON file that describes a pre-configured agent: which
+ * harness (CLI) to use, which model, what system prompt to inject, plus
+ * optional MCP servers and permission flags. Personas live in
+ * `<cwd>/agentworkforce/personas`, the AgentWorkforce home directory, or
+ * any directory the caller passes explicitly.
+ *
+ * Translation from a resolved persona to `{bin, args}` delegates to
+ * `@agentworkforce/harness-kit#buildInteractiveSpec`, so relay always
+ * produces the same launch args the AgentWorkforce CLI does.
+ *
+ * The schema mirrors the AgentWorkforce persona format
+ * (see https://github.com/AgentWorkforce/workforce). Skills installation,
+ * mount policy, sidecar markdown, input rendering, and routing profiles
+ * are deliberately not handled here — callers needing those should use
+ * the `agentworkforce` CLI directly.
+ */
+import { type InteractiveConfigFile } from '@agentworkforce/harness-kit';
+import { HARNESS_VALUES, PERSONA_TIERS, type Harness, type McpServerSpec, type PersonaPermissions, type PersonaTier } from '@agentworkforce/workload-router';
+export type { Harness, McpServerSpec, PersonaPermissions, PersonaTier };
+export { HARNESS_VALUES, PERSONA_TIERS };
+export interface PersonaTierSpec {
+    harness?: Harness;
+    model?: string;
+    systemPrompt?: string;
+    /** Free-form harness settings (reasoning level, timeout) — not consumed by spawnPty today. */
+    harnessSettings?: Record<string, unknown>;
+}
+/** Raw persona file shape. */
+export interface PersonaFile {
+    id: string;
+    intent?: string;
+    description?: string;
+    tags?: string[];
+    /** Used for every tier when set without `tiers`. Ignored when `tiers` is set. */
+    systemPrompt?: string;
+    /** Top-level harness/model — used when there are no tiers. */
+    harness?: Harness;
+    model?: string;
+    permissions?: PersonaPermissions;
+    mcpServers?: Record<string, McpServerSpec>;
+    /** Per-tier overrides. A tier set here takes precedence over the top-level fields. */
+    tiers?: Partial<Record<PersonaTier, PersonaTierSpec>>;
+    /** Inherits from another persona id (looked up in the same search dirs). One level deep. */
+    extends?: string;
+}
+/** A persona file located on disk. */
+export interface DiscoveredPersona {
+    id: string;
+    path: string;
+    spec: PersonaFile;
+}
+/** A persona resolved against a tier — ready for {@link buildPersonaSpawnSpec}. */
+export interface ResolvedPersona {
+    id: string;
+    /** Absolute path to the JSON file the spec came from. */
+    source: string;
+    tier: PersonaTier;
+    harness: Harness;
+    model: string;
+    systemPrompt: string;
+    description?: string;
+    permissions?: PersonaPermissions;
+    mcpServers?: Record<string, McpServerSpec>;
+}
+export interface PersonaLoadOptions {
+    cwd?: string;
+    /** Override the default search-dir cascade. */
+    searchDirs?: string[];
+    /** Extra dirs appended after the default cascade. */
+    extraDirs?: string[];
+    /** Tier to resolve. Defaults to 'best'. */
+    tier?: PersonaTier;
+}
+/**
+ * The shape `AgentRelay.spawnPersona` needs to drive `spawnPty`. Built by
+ * {@link buildPersonaSpawnSpec} from a {@link ResolvedPersona}.
+ */
+export interface PersonaSpawnSpec {
+    /** CLI to launch (matches relay's AgentCli union: 'claude' | 'codex' | 'opencode'). */
+    cli: string;
+    model: string;
+    args: string[];
+    /**
+     * If non-null, append this as the final positional arg to the CLI invocation.
+     * Codex uses this to carry the system prompt; claude / opencode return null.
+     */
+    initialPrompt: string | null;
+    /**
+     * Files the caller must materialize (relative to spawn cwd) before launching
+     * the agent. Used by opencode to drop an `opencode.json` carrying the
+     * persona's agent definition. Empty for claude / codex.
+     */
+    configFiles: InteractiveConfigFile[];
+    /** Non-fatal warnings from the harness-kit translation step. */
+    warnings: string[];
+}
+/**
+ * The default cascade. First match wins for a given persona id.
+ *
+ * 1. `<cwd>/agentworkforce/personas`            (the path most projects pick)
+ * 2. `<cwd>/.agentworkforce/workforce/personas` (workforce CLI's project default)
+ * 3. `<cwd>/agentworkforce/workforce/personas`  (alt workforce layout)
+ * 4. `$AGENT_WORKFORCE_HOME/personas` if set, else `~/.agentworkforce/workforce/personas`
+ */
+export declare function defaultPersonaSearchDirs(cwd?: string): string[];
+/**
+ * List every persona discoverable across the search-dir cascade. When the
+ * same id appears in multiple dirs, only the first match (by cascade order)
+ * is returned.
+ */
+export declare function listPersonas(options?: PersonaLoadOptions): DiscoveredPersona[];
+/**
+ * Find a persona file by id across the search-dir cascade.
+ * Returns undefined if not found.
+ */
+export declare function findPersona(id: string, options?: PersonaLoadOptions): DiscoveredPersona | undefined;
+/**
+ * Load and resolve a persona by id. Searches the cascade, applies the
+ * chosen tier, and resolves a single level of `extends` against the same
+ * cascade. Throws if the persona is missing required fields for the tier.
+ */
+export declare function loadPersona(id: string, options?: PersonaLoadOptions): ResolvedPersona;
+/**
+ * Translate a resolved persona into the bin/args spawnPty needs. Delegates
+ * to {@link buildInteractiveSpec} from `@agentworkforce/harness-kit` so
+ * relay produces the same launch shape the AgentWorkforce CLI does.
+ */
+export declare function buildPersonaSpawnSpec(persona: ResolvedPersona): PersonaSpawnSpec;
+/**
+ * Codex has no system-prompt flag, so the persona's instructions must ride
+ * on the task. Combines them in the same shape the agentworkforce
+ * harness-kit uses for non-interactive codex runs.
+ */
+export declare function composePersonaTask(spec: Pick<PersonaSpawnSpec, 'initialPrompt'>, userTask: string | undefined): string | undefined;
+/** Tracks a file we wrote, so the caller can restore the prior contents. */
+export interface MaterializedConfigFile {
+    /** Absolute path that was written. */
+    path: string;
+    /** Whether a file existed at this path before we wrote. */
+    existed: boolean;
+    /** Prior contents (only set when existed is true). */
+    previous?: string;
+}
+/**
+ * Write each persona config file into `cwd`. Refuses absolute paths or
+ * paths that escape `cwd`. Returns handles the caller can pass to
+ * {@link restorePersonaConfigFiles}.
+ */
+export declare function materializePersonaConfigFiles(cwd: string, files: readonly InteractiveConfigFile[]): MaterializedConfigFile[];
+/**
+ * Restore the original state of files written by
+ * {@link materializePersonaConfigFiles}. Files that did not exist before
+ * are removed; files that did exist are written back to their prior
+ * contents. Errors are swallowed — restore is best-effort cleanup.
+ */
+export declare function restorePersonaConfigFiles(writes: readonly MaterializedConfigFile[]): void;
+//# sourceMappingURL=personas.d.ts.map

package/dist/personas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"personas.d.ts","sourceRoot":"","sources":["../src/personas.ts"],"names":[],"mappings":"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"}

package/dist/personas.js

@@ -0,0 +1,401 @@
+/**
+ * Persona loading and translation.
+ *
+ * A persona is a JSON file that describes a pre-configured agent: which
+ * harness (CLI) to use, which model, what system prompt to inject, plus
+ * optional MCP servers and permission flags. Personas live in
+ * `<cwd>/agentworkforce/personas`, the AgentWorkforce home directory, or
+ * any directory the caller passes explicitly.
+ *
+ * Translation from a resolved persona to `{bin, args}` delegates to
+ * `@agentworkforce/harness-kit#buildInteractiveSpec`, so relay always
+ * produces the same launch args the AgentWorkforce CLI does.
+ *
+ * The schema mirrors the AgentWorkforce persona format
+ * (see https://github.com/AgentWorkforce/workforce). Skills installation,
+ * mount policy, sidecar markdown, input rendering, and routing profiles
+ * are deliberately not handled here — callers needing those should use
+ * the `agentworkforce` CLI directly.
+ */
+import { existsSync, readFileSync, readdirSync, writeFileSync, mkdirSync, rmSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve as resolvePath, sep } from 'node:path';
+import { buildInteractiveSpec, } from '@agentworkforce/harness-kit';
+import { HARNESS_VALUES, PERSONA_TIERS, } from '@agentworkforce/workload-router';
+export { HARNESS_VALUES, PERSONA_TIERS };
+// ── Default search dirs ────────────────────────────────────────────────────
+function expandHome(p) {
+    if (p === '~')
+        return homedir();
+    if (p.startsWith('~/') || p.startsWith('~\\'))
+        return join(homedir(), p.slice(2));
+    return p;
+}
+/**
+ * The default cascade. First match wins for a given persona id.
+ *
+ * 1. `<cwd>/agentworkforce/personas`            (the path most projects pick)
+ * 2. `<cwd>/.agentworkforce/workforce/personas` (workforce CLI's project default)
+ * 3. `<cwd>/agentworkforce/workforce/personas`  (alt workforce layout)
+ * 4. `$AGENT_WORKFORCE_HOME/personas` if set, else `~/.agentworkforce/workforce/personas`
+ */
+export function defaultPersonaSearchDirs(cwd = process.cwd()) {
+    const dirs = [
+        join(cwd, 'agentworkforce', 'personas'),
+        join(cwd, '.agentworkforce', 'workforce', 'personas'),
+        join(cwd, 'agentworkforce', 'workforce', 'personas'),
+    ];
+    const home = process.env.AGENT_WORKFORCE_HOME?.trim();
+    if (home) {
+        dirs.push(join(expandHome(home), 'personas'));
+    }
+    else {
+        dirs.push(join(homedir(), '.agentworkforce', 'workforce', 'personas'));
+    }
+    return dirs;
+}
+function effectiveSearchDirs(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const base = options.searchDirs
+        ? options.searchDirs.map((d) => normalizeDir(d, cwd))
+        : defaultPersonaSearchDirs(cwd);
+    const extras = (options.extraDirs ?? []).map((d) => normalizeDir(d, cwd));
+    return dedupe([...base, ...extras]);
+}
+function normalizeDir(input, cwd) {
+    const expanded = expandHome(input.trim());
+    return isAbsolute(expanded) ? resolvePath(expanded) : resolvePath(cwd, expanded);
+}
+function dedupe(items) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        if (seen.has(item))
+            continue;
+        seen.add(item);
+        out.push(item);
+    }
+    return out;
+}
+// ── Discovery ──────────────────────────────────────────────────────────────
+/**
+ * List every persona discoverable across the search-dir cascade. When the
+ * same id appears in multiple dirs, only the first match (by cascade order)
+ * is returned.
+ */
+export function listPersonas(options = {}) {
+    const dirs = effectiveSearchDirs(options);
+    const byId = new Map();
+    for (const dir of dirs) {
+        if (!existsSync(dir))
+            continue;
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const file of entries) {
+            if (!file.endsWith('.json'))
+                continue;
+            const path = join(dir, file);
+            let spec;
+            try {
+                // Single read avoids a TOCTOU between stat and readFileSync — if the
+                // entry is a directory, vanished, or unreadable we skip it.
+                spec = parsePersonaFile(JSON.parse(readFileSync(path, 'utf8')), path);
+            }
+            catch {
+                continue;
+            }
+            if (!byId.has(spec.id)) {
+                byId.set(spec.id, { id: spec.id, path, spec });
+            }
+        }
+    }
+    return [...byId.values()];
+}
+/**
+ * Find a persona file by id across the search-dir cascade.
+ * Returns undefined if not found.
+ */
+export function findPersona(id, options = {}) {
+    const dirs = effectiveSearchDirs(options);
+    for (const dir of dirs) {
+        if (!existsSync(dir))
+            continue;
+        const candidate = join(dir, `${id}.json`);
+        let candidateBytes;
+        try {
+            // Single read avoids a stat/read TOCTOU. ENOENT (file missing) falls
+            // through to a directory scan for personas with mismatched filenames;
+            // any other read failure or parse failure on a convention-named file
+            // surfaces directly so a typo in the JSON isn't silently treated as
+            // "persona not found".
+            candidateBytes = readFileSync(candidate, 'utf8');
+        }
+        catch (err) {
+            if (err.code !== 'ENOENT')
+                throw err;
+        }
+        if (candidateBytes !== undefined) {
+            const spec = parsePersonaFile(JSON.parse(candidateBytes), candidate);
+            if (spec.id === id)
+                return { id, path: candidate, spec };
+        }
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const file of entries) {
+            if (!file.endsWith('.json'))
+                continue;
+            const path = join(dir, file);
+            try {
+                const spec = parsePersonaFile(JSON.parse(readFileSync(path, 'utf8')), path);
+                if (spec.id === id)
+                    return { id, path, spec };
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    return undefined;
+}
+// ── Resolution ─────────────────────────────────────────────────────────────
+/**
+ * Load and resolve a persona by id. Searches the cascade, applies the
+ * chosen tier, and resolves a single level of `extends` against the same
+ * cascade. Throws if the persona is missing required fields for the tier.
+ */
+export function loadPersona(id, options = {}) {
+    const discovered = findPersona(id, options);
+    if (!discovered) {
+        const dirs = effectiveSearchDirs(options);
+        throw new Error(`Persona "${id}" not found. Searched:\n  ${dirs.join('\n  ')}\n` +
+            'Set searchDirs / extraDirs to include the directory containing the persona file.');
+    }
+    const tier = options.tier ?? 'best';
+    let spec = discovered.spec;
+    if (spec.extends) {
+        const base = findPersona(spec.extends, options);
+        if (!base) {
+            throw new Error(`Persona "${id}" extends "${spec.extends}" but the base could not be found in the search cascade.`);
+        }
+        spec = mergeSpecs(base.spec, spec);
+    }
+    const tierSpec = spec.tiers?.[tier];
+    const harness = (tierSpec?.harness ?? spec.harness);
+    const model = tierSpec?.model ?? spec.model;
+    const systemPrompt = tierSpec?.systemPrompt ?? spec.systemPrompt;
+    if (!harness) {
+        throw new Error(`Persona "${id}" tier "${tier}" has no harness; set tiers.${tier}.harness or top-level harness.`);
+    }
+    if (!HARNESS_VALUES.includes(harness)) {
+        throw new Error(`Persona "${id}" tier "${tier}" uses unsupported harness "${String(harness)}". ` +
+            `Supported: ${HARNESS_VALUES.join(', ')}.`);
+    }
+    if (!model) {
+        throw new Error(`Persona "${id}" tier "${tier}" has no model; set tiers.${tier}.model or top-level model.`);
+    }
+    if (!systemPrompt) {
+        throw new Error(`Persona "${id}" tier "${tier}" has no systemPrompt; set tiers.${tier}.systemPrompt or top-level systemPrompt.`);
+    }
+    return {
+        id: spec.id,
+        source: discovered.path,
+        tier,
+        harness,
+        model,
+        systemPrompt,
+        description: spec.description,
+        permissions: spec.permissions,
+        mcpServers: spec.mcpServers,
+    };
+}
+// ── Merge (extends) ────────────────────────────────────────────────────────
+function mergeSpecs(base, override) {
+    const tiers = {};
+    for (const tier of PERSONA_TIERS) {
+        const baseTier = base.tiers?.[tier];
+        const overrideTier = override.tiers?.[tier];
+        if (overrideTier || baseTier) {
+            tiers[tier] = { ...(baseTier ?? {}), ...(overrideTier ?? {}) };
+        }
+    }
+    return {
+        id: override.id,
+        intent: override.intent ?? base.intent,
+        description: override.description ?? base.description,
+        tags: override.tags ?? base.tags,
+        systemPrompt: override.systemPrompt ?? base.systemPrompt,
+        harness: override.harness ?? base.harness,
+        model: override.model ?? base.model,
+        permissions: mergePermissions(base.permissions, override.permissions),
+        mcpServers: { ...(base.mcpServers ?? {}), ...(override.mcpServers ?? {}) },
+        tiers: Object.keys(tiers).length > 0 ? tiers : undefined,
+    };
+}
+function mergePermissions(base, override) {
+    if (!base && !override)
+        return undefined;
+    const allow = dedupe([...(base?.allow ?? []), ...(override?.allow ?? [])]);
+    const deny = dedupe([...(base?.deny ?? []), ...(override?.deny ?? [])]);
+    return {
+        ...(allow.length > 0 ? { allow } : {}),
+        ...(deny.length > 0 ? { deny } : {}),
+        ...(override?.mode ?? base?.mode ? { mode: override?.mode ?? base?.mode } : {}),
+    };
+}
+// ── Validation ─────────────────────────────────────────────────────────────
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parsePersonaFile(value, source) {
+    if (!isPlainObject(value)) {
+        throw new Error(`${source}: persona must be a JSON object`);
+    }
+    if (typeof value.id !== 'string' || !value.id.trim()) {
+        throw new Error(`${source}: persona.id must be a non-empty string`);
+    }
+    // Validate harness values up front so a typo in the file fails at load time
+    // rather than at spawn — the runtime check in loadPersona stays as a
+    // defense-in-depth guard for callers that bypass parsing.
+    const topHarness = value.harness;
+    if (topHarness !== undefined && !isValidHarness(topHarness)) {
+        throw new Error(`${source}: persona.harness must be one of: ${HARNESS_VALUES.join(', ')} (got ${JSON.stringify(topHarness)})`);
+    }
+    const tiers = value.tiers;
+    if (tiers !== undefined) {
+        if (!isPlainObject(tiers)) {
+            throw new Error(`${source}: persona.tiers must be an object if provided`);
+        }
+        for (const [tierName, tierSpec] of Object.entries(tiers)) {
+            if (!PERSONA_TIERS.includes(tierName))
+                continue; // unknown tier names are ignored
+            if (!isPlainObject(tierSpec))
+                continue;
+            const harness = tierSpec.harness;
+            if (harness !== undefined && !isValidHarness(harness)) {
+                throw new Error(`${source}: persona.tiers.${tierName}.harness must be one of: ${HARNESS_VALUES.join(', ')} (got ${JSON.stringify(harness)})`);
+            }
+        }
+    }
+    return value;
+}
+function isValidHarness(value) {
+    return typeof value === 'string' && HARNESS_VALUES.includes(value);
+}
+// ── Translation: persona → spawn args ──────────────────────────────────────
+/**
+ * Translate a resolved persona into the bin/args spawnPty needs. Delegates
+ * to {@link buildInteractiveSpec} from `@agentworkforce/harness-kit` so
+ * relay produces the same launch shape the AgentWorkforce CLI does.
+ */
+export function buildPersonaSpawnSpec(persona) {
+    const input = {
+        harness: persona.harness,
+        personaId: persona.id,
+        model: persona.model,
+        systemPrompt: persona.systemPrompt,
+        ...(persona.mcpServers ? { mcpServers: persona.mcpServers } : {}),
+        ...(persona.permissions ? { permissions: persona.permissions } : {}),
+    };
+    const spec = buildInteractiveSpec(input);
+    return {
+        cli: spec.bin,
+        model: persona.model,
+        args: [...spec.args],
+        initialPrompt: spec.initialPrompt,
+        configFiles: [...spec.configFiles],
+        warnings: [...spec.warnings],
+    };
+}
+/**
+ * Codex has no system-prompt flag, so the persona's instructions must ride
+ * on the task. Combines them in the same shape the agentworkforce
+ * harness-kit uses for non-interactive codex runs.
+ */
+export function composePersonaTask(spec, userTask) {
+    if (!spec.initialPrompt)
+        return userTask;
+    if (!userTask)
+        return spec.initialPrompt;
+    return `${spec.initialPrompt}\n\nUser task:\n${userTask}`;
+}
+/**
+ * Write each persona config file into `cwd`. Refuses absolute paths or
+ * paths that escape `cwd`. Returns handles the caller can pass to
+ * {@link restorePersonaConfigFiles}.
+ */
+export function materializePersonaConfigFiles(cwd, files) {
+    const out = [];
+    const cwdAbs = resolvePath(cwd);
+    for (const file of files) {
+        if (!file.path)
+            throw new Error('persona config file path must be non-empty');
+        if (isAbsolute(file.path)) {
+            throw new Error(`persona config file path must be relative: ${file.path}`);
+        }
+        const target = resolvePath(cwd, file.path);
+        // Use path.relative for separator-agnostic containment so Windows paths
+        // (`C:\proj\opencode.json`) aren't falsely rejected by a hardcoded '/' check.
+        const rel = relative(cwdAbs, target);
+        if (rel.startsWith('..') || (isAbsolute(rel) && rel !== '')) {
+            throw new Error(`persona config file path escapes cwd: ${file.path}`);
+        }
+        if (rel.split(sep).some((segment) => segment === '..')) {
+            throw new Error(`persona config file path escapes cwd: ${file.path}`);
+        }
+        // Single read with ENOENT detection avoids a TOCTOU between `existsSync`
+        // and `readFileSync`. Any other read error (permissions, EISDIR) bubbles up
+        // — the caller can decide whether to retry or surface to the user.
+        let existed = true;
+        let previous;
+        try {
+            previous = readFileSync(target, 'utf8');
+        }
+        catch (err) {
+            if (err.code === 'ENOENT') {
+                existed = false;
+            }
+            else {
+                throw err;
+            }
+        }
+        mkdirSync(dirname(target), { recursive: true });
+        writeFileSync(target, file.contents, 'utf8');
+        out.push({ path: target, existed, ...(previous !== undefined ? { previous } : {}) });
+    }
+    return out;
+}
+/**
+ * Restore the original state of files written by
+ * {@link materializePersonaConfigFiles}. Files that did not exist before
+ * are removed; files that did exist are written back to their prior
+ * contents. Errors are swallowed — restore is best-effort cleanup.
+ */
+export function restorePersonaConfigFiles(writes) {
+    for (const write of [...writes].reverse()) {
+        try {
+            if (write.existed) {
+                writeFileSync(write.path, write.previous ?? '', 'utf8');
+            }
+            else {
+                rmSync(write.path, { force: true });
+            }
+        }
+        catch (err) {
+            // Best-effort: a failed restore shouldn't break the spawn lifecycle, but
+            // it can leave a stale opencode.json behind, so surface the failure.
+            const msg = err?.message ?? String(err);
+            console.warn(`[personas] failed to restore ${write.path}: ${msg}`);
+        }
+    }
+}
+//# sourceMappingURL=personas.js.map