@sparkelf/dsh-plugin-subagent-settings 0.1.0-rc.10

package/lib/index.js

@@ -0,0 +1,371 @@
+import { settingsNamespace } from "@deepseek-ai/dsh-settings";
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { assertSubagentMaxDepth, settleRun } from "@deepseek-ai/dsh-subagent";
+//#region lib/types/index.js
+/**
+* Model-facing delegation through one configured `ctx.subagents` provider.
+* Provider lifecycle controls tool registration and context-sensitive schema
+* wording. Foreground calls always dispose the run after collection.
+* Background policy is selected by this plugin's configuration: one-shot
+* calls own a plain Task, while continuable calls use
+* `ctx.subagents.startContinuable()`.
+* @module @sparkelf/dsh-plugin-subagent-settings
+*/
+const name = "tool-subagent";
+const inject = [
+	"tools",
+	"subagents",
+	"systemPrompt"
+];
+/** Prompt order after bounded delegation policy and before child reporting. */
+const SUBAGENT_SECTION_ORDER = 116.5;
+/** Build a fresh tool-filter schema before each owner applies its omission default. */
+function toolFilterSchema() {
+	return z.object({
+		allow: z.array(z.string()).default(void 0),
+		deny: z.array(z.string()).default(void 0)
+	});
+}
+const Config = z.object({
+	provider: z.string().required(),
+	settingsNamespace: z.string(),
+	enabled: z.boolean().default(true),
+	toolName: z.string().default("subagent"),
+	enableRunInBackground: z.boolean().default(true),
+	backgroundMode: z.union(["one-shot", "continuable"]).default("one-shot"),
+	agentOptions: z.object({
+		provider: z.string(),
+		model: z.string(),
+		maxTokens: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER)
+	}).default(void 0),
+	persona: z.string(),
+	toolFilter: toolFilterSchema().default(void 0),
+	maxDepth: z.union([z.natural().max(Number.MAX_SAFE_INTEGER), z.const("provider-managed")]).default(0)
+});
+/** Schema for the live user-owned child defaults. */
+const SUBAGENT_SETTINGS_SCHEMA = z.object({
+	enabled: z.boolean().default(false),
+	agentOptions: z.object({
+		provider: z.string().default(void 0),
+		model: z.string().default(void 0),
+		maxTokens: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(void 0)
+	}).default(void 0),
+	persona: z.string().default(void 0),
+	toolFilter: toolFilterSchema().default(void 0),
+	maxDepth: z.union([z.natural().max(Number.MAX_SAFE_INTEGER), z.const("provider-managed")]).default(0)
+});
+/** Render text blocks from the canonical JSON block array without trusting arbitrary values. */
+function outputValueText(values) {
+	return values.filter((value) => typeof value === "object" && value !== null && !Array.isArray(value) && value.type === "text" && typeof value.text === "string").map((value) => value.text).join("");
+}
+/** Settle pending startup without rejecting the task producer contract. */
+async function settleStart(start, signal) {
+	try {
+		return await settleRun(await start);
+	} catch (error) {
+		return signal.aborted && !(error instanceof AggregateError) ? { status: "killed" } : {
+			status: "failed",
+			detail: String(error)
+		};
+	}
+}
+/** A non-`completed` stop reason means the child did not finish cleanly. */
+function stopReasonError(result) {
+	switch (result.stopReason) {
+		case "completed": return;
+		case "aborted": return "subagent run was cancelled";
+		case "error": return "subagent run failed";
+		case "max-tokens": return "subagent run hit its token limit before finishing";
+		case "refusal": return "subagent declined the task";
+		default: return `subagent run ended abnormally (${String(result.stopReason)})`;
+	}
+}
+/**
+* Append provider-authored failure detail and the child's preserved partial
+* answer to a stop-reason error, keeping diagnostic text separate from the
+* child's assistant output.
+* @param error - the stop-reason headline.
+* @param result - the child's terminal result.
+* @returns the headline, diagnostic, and partial text that are present.
+*/
+function withDiagnosticAndPartialText(error, result) {
+	const diagnostic = result.diagnostic === void 0 ? "" : `\nDiagnostic: ${result.diagnostic}`;
+	const text = result.output.filter((block) => block.type === "text").map((block) => block.text).join("");
+	return `${error}${diagnostic}${text.length === 0 ? "" : `\nPartial output before the run ended:\n${text}`}`;
+}
+/**
+* Collect and release one foreground run without letting disposal replace an
+* independent result failure.
+*/
+async function settleForegroundRun(run) {
+	const [execution] = await Promise.allSettled([run.result.then((result) => {
+		const error = stopReasonError(result);
+		if (error !== void 0) throw new Error(withDiagnosticAndPartialText(error, result));
+		return {
+			kind: "foreground",
+			runId: run.id,
+			output: result.output
+		};
+	})]);
+	const [disposal] = await Promise.allSettled([Promise.resolve().then(() => run.dispose())]);
+	if (execution.status === "rejected") {
+		if (disposal.status === "rejected") throw new AggregateError([execution.reason, disposal.reason], `subagent run failed: ${String(execution.reason)}; dispose failed: ${String(disposal.reason)}`);
+		throw execution.reason;
+	}
+	if (disposal.status === "rejected") throw disposal.reason;
+	return execution.value;
+}
+/**
+* Model-facing wording from the provider's conversation-history descriptor
+* ({@link SubagentProvider.inheritsParentContext}).
+* A fresh child needs a standalone prompt; a forked child already sees the
+* conversation's completed turns — telling the model to restate everything
+* (or, worse, that the child "does not see this conversation") would be false
+* for a fork.
+* @param inheritsConversation - whether the child's conversation is seeded
+*   with the parent's completed turns; this says nothing about tool, service,
+*   scope, or authority inheritance.
+* @returns the tool `description` and the `prompt` parameter description.
+*/
+function providerWording(inheritsConversation) {
+	if (inheritsConversation) return {
+		description: "Delegate a task to a subagent that inherits this conversation: a child agent seeded with all completed turns so far (it does not see the current in-flight turn). Use this when the subtask builds on this conversation's context — a follow-up analysis, a review, a continuation — without consuming this conversation's context for the work itself. You receive its result, not its intermediate steps.",
+		promptDescription: "The task for the subagent. It already sees this conversation's completed turns, so build on them freely and state only what is new."
+	};
+	return {
+		description: "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation.",
+		promptDescription: "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+	};
+}
+/** Resolve the model's optional scheduling request into one execution route. */
+function resolveDelegationRun(request, options) {
+	if (!options.backgroundEnabled) {
+		if (request.run_in_background === true) throw new Error("run_in_background is disabled for this tool instance (enableRunInBackground: false)");
+		return { runInBackground: false };
+	}
+	return { runInBackground: request.run_in_background ?? options.continuable };
+}
+/** Project deployment defaults into the live user-owned settings section.
+* @param config - composition-owned child defaults.
+* @returns the fields a user layer may override.
+*/
+function settingsFromConfig(config) {
+	const agentOptions = config.agentOptions;
+	return {
+		...config.enabled === void 0 ? {} : { enabled: config.enabled },
+		...agentOptions === void 0 ? {} : { agentOptions: {
+			...agentOptions.provider === void 0 ? {} : { provider: agentOptions.provider },
+			...agentOptions.model === void 0 ? {} : { model: agentOptions.model },
+			...agentOptions.maxTokens === void 0 ? {} : { maxTokens: agentOptions.maxTokens }
+		} },
+		...config.persona === void 0 ? {} : { persona: config.persona },
+		...config.toolFilter === void 0 ? {} : { toolFilter: config.toolFilter },
+		...config.maxDepth === void 0 ? {} : { maxDepth: config.maxDepth }
+	};
+}
+/** Convert configured nesting generations to the provider's absolute child-depth cap.
+* @param nestingDepth - generations allowed below the first child.
+* @returns the absolute cap enforced by SubagentRuntime.
+*/
+function absoluteChildDepthCap(nestingDepth) {
+	return Math.min(nestingDepth + 1, Number.MAX_SAFE_INTEGER);
+}
+/** Validate live defaults at the earliest point the provider can enforce them.
+* @param value - resolved child defaults.
+* @param provider - currently registered provider, when available.
+*/
+function validateSettings(value, provider) {
+	if (value.maxDepth !== void 0 && value.maxDepth !== "provider-managed") assertSubagentMaxDepth(value.maxDepth);
+	if (value.toolFilter !== void 0 && value.toolFilter.allow === void 0 && value.toolFilter.deny === void 0) throw new Error("tool-subagent: `toolFilter` is configured but names neither `allow` nor `deny` — remove the key or fill the filter");
+	if (provider === void 0) return;
+	if (typeof value.maxDepth === "number" && !provider.capabilities.depthLimit) throw new Error(`tool-subagent: provider "${provider.name}" cannot enforce maxDepth (no depthLimit capability) — set maxDepth: 'provider-managed' to leave the recursion budget to the provider`);
+	if (value.persona !== void 0 && !provider.capabilities.persona) throw new Error("tool-subagent: provider \"" + provider.name + "\" cannot apply persona (no persona capability)");
+	if (value.toolFilter !== void 0 && !provider.capabilities.toolFilter) throw new Error("tool-subagent: provider \"" + provider.name + "\" cannot apply toolFilter (no toolFilter capability)");
+}
+function apply(ctx, config) {
+	const configuredSettings = settingsFromConfig(config);
+	const namespace = config.settingsNamespace === void 0 ? void 0 : settingsNamespace(config.settingsNamespace);
+	const settingsSource = () => {
+		if (namespace === void 0) return configuredSettings;
+		const settings = ctx.get("settings");
+		if (settings === void 0) return configuredSettings;
+		const value = settings.get(namespace);
+		if (value === void 0) throw new Error(`tool-subagent: settings namespace "${namespace}" is not registered by the Host composition`);
+		return value;
+	};
+	validateSettings(settingsSource(), void 0);
+	const backgroundEnabled = config.enableRunInBackground !== false;
+	const continuable = (config.backgroundMode ?? "one-shot") === "continuable";
+	const toolName = config.toolName ?? "subagent";
+	let disposeTool;
+	const mount = (provider) => {
+		validateSettings(settingsSource(), provider);
+		const wording = providerWording(provider.inheritsParentContext);
+		if (continuable && provider.prepareContinuable === void 0) throw new Error(`tool-subagent: provider "${provider.name}" does not support \`backgroundMode: continuable\``);
+		disposeTool = ctx.tools.register(defineTool({
+			name: toolName,
+			description: wording.description + (backgroundEnabled ? continuable ? " This tool runs in the background by default, immediately returns a durable subagent id, and keeps the child conversation available for later turns. When that run settles, the runtime sends the parent a notice containing its outcome and any final assistant message; `send_message` starts a later turn in the same child conversation. Set `run_in_background: false` only when your next action depends on receiving the result." : " This call waits for the result by default. Set `run_in_background: true` to return a job id; collect with `job_output` and stop with `job_kill`." : " This call waits for the subagent and returns its result."),
+			parameters: {
+				description: {
+					type: "string",
+					required: true,
+					description: "A short (3-5 word) description of the delegated task, for display."
+				},
+				prompt: {
+					type: "string",
+					required: true,
+					description: wording.promptDescription
+				},
+				...backgroundEnabled ? { run_in_background: {
+					type: "boolean",
+					description: continuable ? "Whether to run in the background and return a durable subagent id immediately. Defaults to true. Set false to wait for the result when your next action depends on it." : "Whether to run as a background job and return its id. Defaults to false; collect with job_output or stop with job_kill."
+				} } : {}
+			},
+			output: {
+				schema: { oneOf: [
+					{
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							kind: {
+								type: "string",
+								required: true,
+								const: "background"
+							},
+							jobId: {
+								type: "string",
+								required: true
+							}
+						}
+					},
+					{
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							kind: {
+								type: "string",
+								required: true,
+								const: "continuable"
+							},
+							subagentId: {
+								type: "string",
+								required: true
+							}
+						}
+					},
+					{
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							kind: {
+								type: "string",
+								required: true,
+								const: "foreground"
+							},
+							runId: {
+								type: "string",
+								required: true
+							},
+							output: {
+								type: "array",
+								required: true,
+								items: { type: "json" }
+							}
+						}
+					}
+				] },
+				render: (_args, value) => [{
+					type: "text",
+					text: value.kind === "background" ? `started background subagent job ${value.jobId}` : value.kind === "continuable" ? `started subagent ${value.subagentId}` : outputValueText(value.output)
+				}]
+			},
+			isConcurrencySafe: () => true,
+			async execute(args, exec) {
+				const parent = exec.agent;
+				if (!parent) throw new Error("subagent tool requires a calling agent (exec.agent was undefined)");
+				const settings = settingsSource();
+				const maxDepth = typeof settings.maxDepth === "number" ? absoluteChildDepthCap(settings.maxDepth) : void 0;
+				const request = {
+					label: args.description,
+					prompt: [{
+						type: "text",
+						text: args.prompt
+					}],
+					parent,
+					...settings.agentOptions !== void 0 ? { agentOptions: settings.agentOptions } : {},
+					...settings.persona !== void 0 ? { persona: settings.persona } : {},
+					...settings.toolFilter !== void 0 ? { toolFilter: settings.toolFilter } : {},
+					...maxDepth !== void 0 ? { maxDepth } : {}
+				};
+				if (resolveDelegationRun(args, {
+					backgroundEnabled,
+					continuable
+				}).runInBackground) {
+					if (continuable) return {
+						kind: "continuable",
+						subagentId: (await ctx.subagents.startContinuable({
+							provider: config.provider,
+							label: args.description,
+							request,
+							signal: exec.signal
+						})).childId
+					};
+					const jobs = ctx.get("jobs");
+					if (jobs === void 0) throw new Error("background jobs unavailable: load @deepseek-ai/dsh-jobs and @deepseek-ai/dsh-tool-jobs");
+					return {
+						kind: "background",
+						jobId: jobs.start({
+							kind: "subagent",
+							label: args.description,
+							owner: parent,
+							run: () => {
+								const controller = new AbortController();
+								return {
+									cancel: (reason) => {
+										controller.abort(reason ?? "background subagent task killed");
+									},
+									done: settleStart(ctx.subagents.start(config.provider, {
+										...request,
+										signal: controller.signal
+									}), controller.signal)
+								};
+							}
+						})
+					};
+				}
+				return settleForegroundRun(await ctx.subagents.start(config.provider, {
+					...request,
+					signal: exec.signal
+				}));
+			}
+		}));
+	};
+	const reconcile = (provider) => {
+		if (!(settingsSource().enabled !== false) || provider === void 0) {
+			disposeTool?.();
+			disposeTool = void 0;
+			return;
+		}
+		if (disposeTool === void 0) mount(provider);
+	};
+	ctx.on("subagent/provider-added", (provider) => {
+		if (provider.name === config.provider) reconcile(provider);
+	});
+	ctx.on("subagent/provider-removed", (name) => {
+		if (name === config.provider) reconcile(void 0);
+	});
+	if (namespace !== void 0) ctx.on("settings/updated", (changedNamespace) => {
+		if (changedNamespace === namespace) reconcile(ctx.subagents.getProvider(config.provider));
+	});
+	const present = ctx.subagents.getProvider(config.provider);
+	reconcile(present);
+	if (present === void 0 && settingsSource().enabled !== false) ctx.logger.info(`subagent provider "${config.provider}" not registered yet; the "${config.toolName ?? "subagent"}" tool will register when it appears`);
+	if (backgroundEnabled && continuable) ctx.systemPrompt.section({
+		name: `tool:${toolName}`,
+		order: SUBAGENT_SECTION_ORDER,
+		text: (context) => disposeTool === void 0 || ctx.tools.get(toolName, context.scope) === void 0 ? "" : `Use ${toolName} in the background by default. Start independent delegations together in one assistant message and continue useful work while they run. Set \`run_in_background: false\` only when your next action depends on that subagent's result. When a background run settles, the runtime sends you a notice containing its outcome and any final assistant message.`
+	});
+}
+//#endregion
+export { Config, SUBAGENT_SETTINGS_SCHEMA, apply, inject, name, settingsFromConfig, validateSettings };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@sparkelf/dsh-plugin-subagent-settings`.
+* @module @sparkelf/dsh-plugin-subagent-settings/invariant
+*/
+const PACKAGE_NAME = "@sparkelf/dsh-plugin-subagent-settings";
+/** Cordis companion plugin name. */
+const name = "tool-subagent-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this model-facing adapter has no independent lifecycle stream; execution
+* relations are owned by the capability seam it calls.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/startup.js

@@ -0,0 +1,28 @@
+import { SUBAGENT_SETTINGS_SCHEMA, settingsFromConfig, validateSettings } from "./index.js";
+import { settingsNamespace } from "@deepseek-ai/dsh-settings";
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/startup.js
+const name = "tool-subagent-settings";
+const inject = ["subagents"];
+const Config = z.intersect([z.object({
+	settingsNamespace: z.string().required(),
+	provider: z.string().required()
+}), SUBAGENT_SETTINGS_SCHEMA]);
+/** Register one Subagent settings namespace at Host lifetime.
+* @param ctx - Host plugin context carrying Settings and Subagent services.
+* @param config - namespace, provider, and composition defaults.
+*/
+function apply(ctx, config) {
+	const namespace = settingsNamespace(config.settingsNamespace);
+	const base = settingsFromConfig(config);
+	ctx.inject(["settings"], (sctx) => {
+		sctx.settings.register(namespace, SUBAGENT_SETTINGS_SCHEMA, {
+			base,
+			validate: (value) => {
+				validateSettings(value, ctx.subagents.getProvider(config.provider));
+			}
+		});
+	});
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/types/client/SubagentCard.d.ts

@@ -0,0 +1,20 @@
+import type { ReactNode } from 'react';
+import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
+import type { SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { SubagentEntryView, SubagentSettingsState, SubagentSettingsValue } from './subagent-store.ts';
+/** Browser-side actions and snapshot supplied by the section registration. */
+export interface SubagentSettingsSectionInjected {
+    hooks: {
+        subagentSettings: SnapshotStore<SubagentSettingsState>;
+    };
+    ensure: () => void;
+    stage: (entry: SubagentEntryView, value: SubagentSettingsValue) => void;
+    save: (entry: SubagentEntryView) => Promise<void>;
+    reset: (entry: SubagentEntryView) => void;
+    discard: (entry: SubagentEntryView) => void;
+}
+/** Props for the unified subagent settings section. */
+export type SubagentSettingsSectionProps = PropsRuntime<'settings.section'> & PropsLocale<'settings.subagents'> & InjectFace<SubagentSettingsSectionInjected>;
+/** Render one card whose mode tabs preserve independent settings namespaces. */
+export declare function SubagentSettingsSection(props: SubagentSettingsSectionProps): ReactNode;
+//# sourceMappingURL=SubagentCard.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,17 @@
+/** Browser Settings section for the two shipped settings-backed delegation entries. */
+import type { Context } from '@deepseek-ai/cordis';
+import { type SubagentSettingsLocaleKey } from './locales.ts';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** Product copy for the Subagent Settings section. */
+        'settings.subagents': SubagentSettingsLocaleKey;
+    }
+}
+/** Required browser services. */
+export declare const inject: string[];
+/**
+ * Mount the dedicated Subagents Settings section.
+ * @param ctx - Browser plugin context.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,7 @@
+/** Typed dictionaries owned by the Subagent settings capability. */
+export type SubagentSettingsLocaleKey = 'nav' | 'reset' | 'readOnly' | 'save' | 'saving' | 'discard' | 'unsaved' | 'saveFailed' | 'subagentTitle' | 'subagentIntro' | 'subagentModes' | 'subagentContinuous' | 'subagentOneShot' | 'subagentContinuousDescription' | 'subagentOneShotDescription' | 'subagentEnableContinuous' | 'subagentEnableOneShot' | 'subagentModel' | 'subagentFollowParent' | 'subagentFixedModel' | 'subagentProvider' | 'subagentModelId' | 'subagentMaxTokens' | 'subagentPersona' | 'subagentInheritPersona' | 'subagentOverridePersona' | 'subagentPersonaPlaceholder' | 'subagentTools' | 'subagentAllTools' | 'subagentAllowTools' | 'subagentDenyTools' | 'subagentToolNamesPlaceholder' | 'subagentDepth' | 'subagentProviderManaged';
+/** English product copy. */
+export declare const en: Record<SubagentSettingsLocaleKey, string>;
+/** Simplified Chinese product copy. */
+export declare const zh: Record<SubagentSettingsLocaleKey, string>;
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/subagent-store.d.ts

@@ -0,0 +1,74 @@
+/** Shared Settings-scope state for the unified subagent settings section. */
+import { type SnapshotStore } from '@deepseek-ai/dsh-client-store';
+import type { SettingsScope } from '@deepseek-ai/dsh-client-ui-settings/client';
+/** One editable value from a tool-subagent settings namespace. */
+export interface SubagentSettingsValue {
+    enabled?: boolean;
+    agentOptions?: Partial<{
+        provider: string;
+        model: string;
+        maxTokens: number;
+    }>;
+    persona?: string;
+    toolFilter?: {
+        allow?: string[];
+        deny?: string[];
+    };
+    maxDepth?: number | 'provider-managed';
+}
+/** Settings namespaces owned by the two shipped delegation entries. */
+export type SubagentSettingsNamespace = 'subagent' | 'subagent-fork';
+/** One shipped delegation entry and its effective settings. */
+export interface SubagentEntryView {
+    ns: SubagentSettingsNamespace;
+    kind: 'spawn' | 'fork';
+    label: string;
+    context: 'fresh' | 'forked';
+    background: 'continuable' | 'one-shot';
+    value: SubagentSettingsValue;
+}
+/** State rendered by the unified settings section. */
+export interface SubagentSettingsState {
+    writable: boolean;
+    entries: readonly SubagentEntryView[];
+    drafts: Readonly<Partial<Record<SubagentSettingsNamespace, SubagentSettingsValue>>>;
+    saving: boolean;
+    saveErrors: Readonly<Partial<Record<SubagentSettingsNamespace, true>>>;
+}
+type SubagentScopes = Record<SubagentSettingsNamespace, SettingsScope<SubagentSettingsValue>>;
+/** Settings controller shared by both mode panels. */
+export declare class SubagentSettingsStore {
+    private readonly scopes;
+    /** Reactive state shared by both mode panels. */
+    readonly store: SnapshotStore<SubagentSettingsState>;
+    private readonly unsubscribers;
+    private started;
+    /**
+     * @param scopes - namespace scopes derived from the browser's shared Settings mirror.
+     */
+    constructor(scopes: SubagentScopes);
+    /** Start following both scopes and load model choices once. */
+    ensure(): void;
+    /** Stop following the two Settings scopes. */
+    dispose(): void;
+    /** Stage one entry until its plugin card is saved.
+     * @param entry - entry being edited.
+     * @param value - complete staged user section.
+     */
+    stage(entry: SubagentEntryView, value: SubagentSettingsValue): void;
+    /** Persist one staged entry through its Settings scope.
+     * @param entry - entry whose card initiated the save.
+     */
+    save(entry: SubagentEntryView): Promise<void>;
+    /** Stage one entry back to its deployment defaults.
+     * @param entry - entry being reset.
+     */
+    reset(entry: SubagentEntryView): void;
+    /** Discard one card's staged edit without writing it.
+     * @param entry - entry whose draft is discarded.
+     */
+    discard(entry: SubagentEntryView): void;
+    private derive;
+}
+export {};
+//# sourceMappingURL=subagent-store.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Model-facing delegation through one configured `ctx.subagents` provider.
+ * Provider lifecycle controls tool registration and context-sensitive schema
+ * wording. Foreground calls always dispose the run after collection.
+ * Background policy is selected by this plugin's configuration: one-shot
+ * calls own a plain Task, while continuable calls use
+ * `ctx.subagents.startContinuable()`.
+ * @module @sparkelf/dsh-plugin-subagent-settings
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { SubagentProvider } from '@deepseek-ai/dsh-subagent';
+export declare const name = "tool-subagent";
+export declare const inject: string[];
+/** Config: which registered provider this tool delegates to, plus child defaults. */
+export interface Config {
+    /** The `ctx.subagents` provider name to start runs on (e.g. `spawn`, `acp`). */
+    provider: string;
+    /** Optional Host-registered settings namespace for live child-default overrides. */
+    settingsNamespace?: string;
+    /** Whether this model-facing delegation entry is registered (default true). */
+    enabled?: boolean;
+    /**
+     * Model-facing tool name (default `subagent`). Each loaded instance must use
+     * a distinct name.
+     */
+    toolName?: string;
+    /**
+     * Expose `run_in_background` (default true). Disabled instances omit the
+     * parameter and reject forced background calls.
+     */
+    enableRunInBackground?: boolean;
+    /**
+     * Background execution policy (default `one-shot`). `one-shot` defaults calls
+     * to foreground; `continuable` defaults them to background, requires a provider
+     * with the `prepareContinuable` capability, and returns the durable child id.
+     * Follow-up adapters remain independently optional.
+     */
+    backgroundMode?: 'one-shot' | 'continuable';
+    /**
+     * Agent options applied to every child; omitted fields use child-loop defaults.
+     */
+    agentOptions?: AgentOptions;
+    /**
+     * Per-child persona that shadows `deployment:persona`. Requires the
+     * provider's `persona` capability; omission preserves the deployment persona.
+     */
+    persona?: string;
+    /**
+     * Tool filter applied to every child. Filtered tools disappear from its
+     * prompt and reject execution. Requires the provider's `toolFilter`
+     * capability; unknown names fail startup.
+     */
+    toolFilter?: {
+        /** Global tool names the child keeps; everything else is removed. */
+        allow?: string[];
+        /** Global tool names removed from the child. */
+        deny?: string[];
+    };
+    /**
+     * Additional delegation generations below a direct child: a non-negative safe
+     * integer (default `0`; `0` permits a child but forbids grandchildren), or
+     * `'provider-managed'` to send no cap. A numeric cap
+     * requires the provider's `depthLimit` capability (mount fails loud
+     * otherwise). The provider checks the calling agent's current depth at every
+     * start; the tool remains model-visible so runtime policy owns rejection.
+     * `'provider-managed'` is for an out-of-process provider whose recursion
+     * budget belongs to the child runtime or its own deployment.
+     */
+    maxDepth?: number | 'provider-managed';
+}
+export declare const Config: z<Config>;
+/** User-owned entry state and child defaults that can change without rebuilding the Host. */
+export interface SubagentSettings {
+    /** Whether the Host exposes this delegation mode to agents. */
+    enabled?: boolean;
+    /** Provider and model overrides; omission follows the parent agent. */
+    agentOptions?: Partial<Pick<AgentOptions, 'provider' | 'model' | 'maxTokens'>>;
+    /** Child persona that shadows the deployment persona when set. */
+    persona?: string;
+    /** Global tool names the child keeps or removes. */
+    toolFilter?: Config['toolFilter'];
+    /** Delegation generations below a direct child, or provider-owned depth management. */
+    maxDepth?: Config['maxDepth'];
+}
+/** Schema for the live user-owned child defaults. */
+export declare const SUBAGENT_SETTINGS_SCHEMA: z<SubagentSettings>;
+/** Project deployment defaults into the live user-owned settings section.
+ * @param config - composition-owned child defaults.
+ * @returns the fields a user layer may override.
+ */
+export declare function settingsFromConfig(config: SubagentSettings): SubagentSettings;
+/** Validate live defaults at the earliest point the provider can enforce them.
+ * @param value - resolved child defaults.
+ * @param provider - currently registered provider, when available.
+ */
+export declare function validateSettings(value: SubagentSettings, provider: SubagentProvider | undefined): void;
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@sparkelf/dsh-plugin-subagent-settings`.
+ * @module @sparkelf/dsh-plugin-subagent-settings/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-subagent-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map