@robota-sdk/agent-preset 3.0.0-beta.100

package/README.md

@@ -0,0 +1,124 @@
+# @robota-sdk/agent-preset
+
+Presets and output styles for the Robota SDK. A preset is a named bundle of
+`@robota-sdk/agent-framework` session option overrides: persona, model and effort, permission
+posture, command-module selection, execution capabilities and autonomy. An output style is a named
+set of instructions for how responses are written. This package owns both contracts, the built-in
+presets and styles, and the registries that resolve them.
+
+## Installation
+
+```bash
+npm install @robota-sdk/agent-preset @robota-sdk/agent-framework
+```
+
+Requires Node.js 22.12 or later.
+
+## Presets
+
+```typescript
+import { createPresetRegistry } from '@robota-sdk/agent-preset';
+
+// A registry holds its own list: the built-ins plus any external presets you pass.
+// Two registries in one process never see each other's presets.
+const registry = createPresetRegistry();
+
+// Resolve a preset into session option overrides.
+// Precedence (low → high): preset < cliOverrides < explicit.
+const options = registry.resolvePreset('careful-reviewer', {
+  cliOverrides: { model: 'some-model' },
+  explicit: { temperature: 0.2 },
+});
+
+// List presets for a picker, or read one definition.
+const summaries = registry.listPresets(); // [{ id, title, description }, ...]
+const preset = registry.getPreset('autonomous-builder');
+console.log(options, summaries, preset);
+```
+
+Resolving an unknown ID throws, naming the available presets. `deniedTools` from every layer are
+combined rather than replaced. When no layer sets `permissionMode`, it comes from
+`defaultPermissionMode`, or else from `autonomy` (`ask-first` and `balanced` map to `default`,
+`act-first` to `acceptEdits`).
+
+### Built-in presets
+
+| ID                   | Posture                                                                                |
+| -------------------- | -------------------------------------------------------------------------------------- |
+| `default`            | No overrides; resolving it reproduces the standard agent behaviour                     |
+| `autonomous-builder` | High effort, acts first, parallel subagents, self-verification                         |
+| `careful-reviewer`   | High effort, asks first, no parallel subagents, self-verification                      |
+| `neutral-executor`   | Medium effort, balanced autonomy, follows instructions literally, no self-verification |
+
+`defaultPreset` and `autonomousBuilderPreset` are also exported as values.
+
+### External presets
+
+External presets are JSON files in a directory your product chooses:
+
+```typescript
+import { createPresetRegistry, loadExternalPresetsFromDir } from '@robota-sdk/agent-preset';
+
+const { presets, loaded, errors } = loadExternalPresetsFromDir('/path/to/my-app/presets');
+for (const { file, error } of errors) console.warn(`${file}: ${error}`);
+
+const registry = createPresetRegistry(presets);
+console.log(loaded);
+```
+
+Each file is checked with `validateExternalPreset`. A malformed file, an ID that collides with a
+built-in, or a duplicate ID is reported in `errors` and skipped; the rest still load. A missing
+directory yields no presets. `partitionExternalPresets` applies the same collision rules to presets
+you already have in memory.
+
+## Output styles
+
+`createOutputStyleRegistry(sources)` combines the built-in styles (`default`, `concise`,
+`proactive`, `explanatory`, `learning`) with Markdown style files from sources you pass
+(`managed`, `user` or `project` scope, each with a precedence; a higher precedence wins). A style
+file's ID is its file name without `.md`; it has optional frontmatter (`name`, `description`,
+`keep-coding-instructions`, `token-cost`) and a non-empty body with the instructions. A file cannot
+replace a built-in style. `loadOutputStylesFromSources` returns the styles plus per-file errors, and
+`parseOutputStyleFile` parses one file.
+
+```typescript
+import { createOutputStyleRegistry } from '@robota-sdk/agent-preset';
+
+const styles = createOutputStyleRegistry([
+  {
+    scope: 'user',
+    displayName: '~/.my-app/output-styles',
+    precedence: 1,
+    files: [
+      {
+        fileName: 'terse.md',
+        content: '---\nname: Terse\ntoken-cost: low\n---\nAnswer in as few words as possible.',
+      },
+    ],
+  },
+]);
+
+console.log(styles.listOutputStyles().map((style) => style.id));
+const terse = styles.getOutputStyle('terse');
+console.log(terse?.instructions);
+```
+
+## Where it sits
+
+```
+agent-framework   ← session option types this package overrides
+    ↑
+agent-preset      ← this package
+    ↑
+agent-cli, agent-command, agent-product   ← create registries and apply presets
+```
+
+This package depends only on `@robota-sdk/agent-framework` and does not re-export it.
+
+## Documentation
+
+- [docs/SPEC.md](./docs/SPEC.md) — package contract, precedence and design decisions
+
+## License
+
+This package is dual-licensed under the [GNU AGPL-3.0](../../LICENSE) or a [commercial license](../../COMMERCIAL.md). See [LICENSING.md](../../LICENSING.md).

package/dist/node/index.cjs

@@ -0,0 +1,6 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require("node:fs"),t=require("node:path"),n=require("@robota-sdk/agent-framework");const r={id:`default`,title:`Default`,description:`Neutral baseline preset — no overrides; reproduces the standard agent behaviour.`},i={id:`autonomous-builder`,title:`Autonomous Builder`,description:`Proactive, self-verifying builder posture — high effort, acts first, dispatches parallel subagents (proactive autonomous-builder persona; original English wording).`,effort:`high`,autonomy:`act-first`,enableParallelSubagents:!0,selfVerification:!0,persona:[`You are a proactive, high-autonomy builder. When you have enough to proceed, proceed and`,`complete the task — act rather than stop to ask. Keep going through the points where a more`,`hesitant assistant would pause for confirmation, and only check in when something is genuinely`,`ambiguous or risky.`,``,`Stay inside the scope of the task. Do the simplest thing that works; do not refactor, add`,`abstractions, or expand scope beyond what was asked. Handle the adjacent detail that the task`,`plainly needs, but resist turning a focused change into a sweeping one.`,``,`After making changes, verify your own work — run the tests, re-read the goal, and confirm the`,`result actually matches what was requested before you call it done.`,``,`Ground your claims in evidence. Before reporting progress, check each claim against an actual`,`tool result from this session; if something is not yet verified, say so plainly rather than`,`implying it is finished.`,``,`Be warm and honest without being sycophantic — tell people what is useful, not just what they`,`want to hear. Stay even-handed and let your conclusions follow from the evidence. When you get`,`something wrong, own it directly, correct it, and move on.`,``,`Lead with the outcome. Report results plainly instead of narrating each step, keep formatting`,`light, and stay concise.`].join(`
+`)},a={id:`careful-reviewer`,title:`Careful Reviewer`,description:`Conservative, ask-first reviewing posture — reads and plans before changing, prompts on write/exec, self-verifies, runs focused (no parallel subagents) at high effort.`,effort:`high`,autonomy:`ask-first`,enableParallelSubagents:!1,selfVerification:!0,persona:[`You are a careful, review-oriented assistant. Read and analyse before you change anything —`,`understand the surrounding code and context first, then lay out a short plan for the change and`,`wait for confirmation before you write or run things that have side effects.`,``,`When you propose a change, explain why — the reasoning behind it and the trade-offs against the`,`alternatives you considered, so the choice can be reviewed rather than taken on trust.`,``,`Stay conservative in scope. Make the change that was asked for and the detail it plainly needs;`,`do not widen the blast radius with unrequested refactors or rewrites.`,``,`Ground your claims in evidence. Before reporting progress or completion, check each claim against`,`an actual tool result from this session; if something is not yet verified, say so plainly rather`,`than implying it is done.`,``,`Be warm and honest without being sycophantic — tell people what is useful, not just what they`,`want to hear. Stay even-handed and let your conclusions follow from the evidence. When you get`,`something wrong, own it directly, correct it, and move on.`].join(`
+`)},o={id:`neutral-executor`,title:`Neutral Executor`,description:`Thin, steerable executor — follows instructions literally, minimal editorialising, strict scope, terse output; balanced autonomy, no parallel subagents, no self-verification, medium effort for predictable scripted use (neutral-alignment work-style; original English wording).`,effort:`medium`,autonomy:`balanced`,enableParallelSubagents:!1,selfVerification:!1,persona:[`Follow the system and user instructions literally. Do what was asked, the way it was asked, and`,`defer to the given instructions over your own preferences.`,``,`Editorialise as little as possible. Skip unrequested commentary, caveats, and asides — give the`,`result, not a narration of it.`,``,`Stay strictly in scope. Make only the change that was requested and the detail it plainly needs;`,`do not add adjacent refactors, comments, or features that were not asked for.`,``,`Keep output terse. Prefer the shortest response that fully answers, so the result is predictable`,`and easy to consume in a script or pipeline.`].join(`
+`)},s={"ask-first":`default`,balanced:`default`,"act-first":`acceptEdits`},c=[r,i,a,o];function l(e){let t=new Set(c.map(e=>e.id)),n=[],r=[];for(let i of e){if(t.has(i.id)){r.push({id:i.id,reason:`collides with built-in preset`});continue}if(n.some(e=>e.id===i.id)){r.push({id:i.id,reason:`duplicate preset id`});continue}n.push(i)}return{accepted:n,rejected:r}}function u(e){let{id:t,title:n,description:r,...i}=e;return i}function d(e){return Object.fromEntries(Object.entries(e).filter(([,e])=>e!==void 0))}function f(e,t){if(!t)return e;let n={...e,...d(t)};return t.deniedTools!==void 0||e.deniedTools!==void 0?{...n,deniedTools:p(e.deniedTools,t.deniedTools)}:n}function p(e,t){return[...new Set([...e??[],...t??[]])]}function m(e,t,n={}){let r=e.find(e=>e.id===t);if(!r){let n=e.map(e=>e.id).join(`, `);throw Error(`Unknown preset: "${t}". Available presets: ${n}.`)}let i=u(r);return i=f(i,n.cliOverrides),i=f(i,n.explicit),g(i)}function h(e=[]){let t=[...c,...l(e).accepted];return{resolvePreset:(e,n={})=>m(t,e,n),getPreset:e=>t.find(t=>t.id===e),listPresets:()=>t.map(({id:e,title:t,description:n})=>({id:e,title:t,description:n}))}}function g(e){return e.permissionMode===void 0?e.defaultPermissionMode===void 0?e.autonomy===void 0?e:{...e,permissionMode:s[e.autonomy]}:{...e,permissionMode:e.defaultPermissionMode}:e}const _=[`ask-first`,`act-first`,`balanced`],v=n.VALID_PERMISSION_MODES;function y(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function b(e){return Array.isArray(e)&&e.every(e=>typeof e==`string`)}function x(e,t){let n=[[`persona`,e.persona,e=>t.persona=e],[`systemPrompt`,e.systemPrompt,e=>t.systemPrompt=e],[`appendSystemPrompt`,e.appendSystemPrompt,e=>t.appendSystemPrompt=e],[`agentName`,e.agentName,e=>t.agentName=e],[`model`,e.model,e=>t.model=e],[`language`,e.language,e=>t.language=e]];for(let[e,t,r]of n)if(t!==void 0){if(typeof t!=`string`)return`${e}: expected a string`;r(t)}}function S(e,t){let n=[[`temperature`,e.temperature,e=>t.temperature=e],[`maxOutputTokens`,e.maxOutputTokens,e=>t.maxOutputTokens=e]];for(let[e,t,r]of n)if(t!==void 0){if(typeof t!=`number`||Number.isNaN(t))return`${e}: expected a number`;r(t)}let r=[[`enableParallelSubagents`,e.enableParallelSubagents,e=>t.enableParallelSubagents=e],[`selfVerification`,e.selfVerification,e=>t.selfVerification=e]];for(let[e,t,n]of r)if(t!==void 0){if(typeof t!=`boolean`)return`${e}: expected a boolean`;n(t)}}function C(e,t){if(e.effort!==void 0){if(typeof e.effort!=`string`)return`effort: expected a string`;try{let r=(0,n.parseModelEffort)(e.effort,`effort`);if(r===void 0)return`effort: expected a Core-owned effort selection`;t.effort=r}catch(e){return`effort: ${e instanceof Error?e.message:String(e)}`}}if(e.autonomy!==void 0){if(!_.includes(e.autonomy))return`autonomy: expected one of ${_.join(`, `)}`;t.autonomy=e.autonomy}let r=[[`permissionMode`,e.permissionMode,e=>t.permissionMode=e],[`defaultPermissionMode`,e.defaultPermissionMode,e=>t.defaultPermissionMode=e]];for(let[e,t,n]of r)if(t!==void 0){if(!v.includes(t))return`${e}: expected one of ${v.join(`, `)}`;n(t)}}function w(e,t){let n=[[`allowedTools`,e.allowedTools,e=>t.allowedTools=e],[`deniedTools`,e.deniedTools,e=>t.deniedTools=e],[`enabledCommandModules`,e.enabledCommandModules,e=>t.enabledCommandModules=e],[`disabledCommandModules`,e.disabledCommandModules,e=>t.disabledCommandModules=e]];for(let[e,t,r]of n)if(t!==void 0){if(!b(t))return`${e}: expected an array of strings`;r(t)}}function T(e){if(!y(e))return{ok:!1,error:`preset: expected a non-null object`};let t=[[`id`,e.id],[`title`,e.title],[`description`,e.description]];for(let[e,n]of t)if(typeof n!=`string`||n.length===0)return{ok:!1,error:`${e}: expected a non-empty string`};let n={},r=x(e,n)??S(e,n)??C(e,n)??w(e,n);return r===void 0?{ok:!0,preset:{id:e.id,title:e.title,description:e.description,...n}}:{ok:!1,error:r}}function E(n){if(!(0,e.existsSync)(n))return{presets:[],loaded:[],errors:[]};let r=[],i=[],a=new Map,o=(0,e.readdirSync)(n).filter(e=>e.endsWith(`.json`));for(let s of o){let o=(0,t.join)(n,s),c;try{c=JSON.parse((0,e.readFileSync)(o,`utf8`))}catch(e){r.push({file:s,error:e instanceof Error?e.message:String(e)});continue}let l=T(c);if(!l.ok){r.push({file:s,error:l.error});continue}i.push(l.preset),a.set(l.preset.id,s)}let{accepted:s,rejected:c}=l(i);for(let e of c)r.push({file:a.get(e.id)??e.id,error:e.reason});return{presets:s,loaded:s.map(e=>e.id),errors:r}}const D=[{id:`default`,name:`Default`,description:`The ordinary response style.`,instructions:``,keepCodingInstructions:!0,tokenCost:`baseline`,source:`built-in`},{id:`concise`,name:`Concise`,description:`Lead with the result and keep routine responses short.`,instructions:`Lead with the answer and skip routine preamble or tool narration. Keep responses concise while doing the same engineering work. Expand fully when asked for detail. Always keep error reports, security warnings and destructive-action confirmations complete.`,keepCodingInstructions:!0,tokenCost:`low`,source:`built-in`},{id:`proactive`,name:`Proactive`,description:`Take the next reasonable step without pausing on routine choices.`,instructions:`Act on reasonable routine assumptions and take the next useful step. State assumptions when they matter. The active permission mode remains authoritative; this style never grants, changes, or bypasses permission.`,keepCodingInstructions:!0,tokenCost:`medium`,source:`built-in`},{id:`explanatory`,name:`Explanatory`,description:`Teach the reasoning and trade-offs behind the answer.`,instructions:`Explain the reasoning, important trade-offs, and relevant terminology as you work. Keep the explanation connected to the requested outcome and do not omit complete error, security, or destructive-action guidance.`,keepCodingInstructions:!0,tokenCost:`high`,source:`built-in`},{id:`learning`,name:`Learning`,description:`Teach by marking useful gaps for the human to fill.`,instructions:`Teach the requested subject step by step. Mark a small number of useful gaps with [Your turn:] and invite the human to fill them before revealing the explanation. Never turn safety, security, error, or destructive-action guidance into a gap.`,keepCodingInstructions:!0,tokenCost:`high`,source:`built-in`}],O=new Set([`baseline`,`low`,`medium`,`high`,`unspecified`]);function k(e){return e.replace(/^(?:"([\s\S]*)"|'([\s\S]*)')$/,`$1$2`)}function A(e,t){if(t===`true`)return!0;if(t===`false`)return!1;throw Error(`${e}: expected boolean, received "${t}"`)}function j(e,t){let n=t.split(`
+`);if(n[0]?.trim()!==`---`)throw Error(`frontmatter: expected an opening --- marker`);let r={},i=-1;for(let e=1;e<n.length;e+=1){let t=n[e];if(t.trim()===`---`){i=e;break}if(t.trim()===``)continue;let a=/^([a-z][a-z0-9-]*):\s*(\S[^\n\r\u2028\u2029]*)?$/.exec(t);if(!a)throw Error(`frontmatter: invalid entry at line ${e+1}`);let o=a[1];if(r[o]!==void 0)throw Error(`frontmatter.${o}: duplicate field`);r[o]=k((a[2]??``).trim())}if(i<0)throw Error(`frontmatter: expected a closing --- marker`);let a=Object.keys(r).filter(e=>![`name`,`description`,`keep-coding-instructions`,`token-cost`].includes(e));if(a.length>0)throw Error(`frontmatter.${a[0]}: unknown field`);return{values:r,instructions:n.slice(i+1).join(`
+`).trim()}}function M(e){let n=(0,t.basename)(e,(0,t.extname)(e)).trim();if(!/^[a-z0-9][a-z0-9-]*$/i.test(n))throw Error(`id: expected the Markdown filename stem to be a slug, received "${n}"`);return n.toLowerCase()}function N(e,n){if(!e.fileName.endsWith(`.md`))throw Error(`file: expected a .md output-style file`);let r=M(e.fileName),i=j(e.fileName,e.content),a=i.values.name?.trim()||(0,t.basename)(e.fileName,`.md`),o=i.values.description?.trim()||`Custom output style: ${a}`,s=i.values[`keep-coding-instructions`]!==void 0&&A(`frontmatter.keep-coding-instructions`,i.values[`keep-coding-instructions`]),c=i.values[`token-cost`]??`unspecified`;if(!O.has(c))throw Error(`frontmatter.token-cost: expected baseline|low|medium|high|unspecified, received "${c}"`);if(i.instructions.length===0)throw Error(`body: expected non-empty style instructions`);return{id:r,name:a,description:o,instructions:i.instructions,keepCodingInstructions:s,tokenCost:c,source:n}}function P(e){return{id:e.id,name:e.name,description:e.description,tokenCost:e.tokenCost,source:e.source}}function F(e){let t=new Map,n=[];for(let e of D)t.set(e.id,e);let r=[...e].sort((e,t)=>e.precedence-t.precedence);for(let e of r){let r=new Set;for(let i of[...e.files].sort((e,t)=>e.fileName.localeCompare(t.fileName))){let a=`${e.displayName}/${i.fileName}`,o;try{o=N(i,e.scope)}catch(e){n.push({file:a,error:e instanceof Error?e.message:String(e)});continue}if(r.has(o.id)){n.push({file:a,error:`duplicate style id "${o.id}" in source`});continue}if(r.add(o.id),t.get(o.id)?.source===`built-in`){n.push({file:a,error:`style id "${o.id}" collides with a built-in`});continue}t.set(o.id,o)}}return{styles:[...t.values()],loaded:[...t.values()].filter(e=>e.source!==`built-in`).map(e=>e.id),errors:n}}function I(e=[]){let t=F(e),n=new Map(t.styles.map(e=>[e.id,e]));return{listOutputStyles:()=>t.styles.map(P),getOutputStyle:e=>n.get(e)}}exports.autonomousBuilderPreset=i,exports.builtInOutputStyles=D,exports.createOutputStyleRegistry=I,exports.createPresetRegistry=h,exports.defaultPreset=r,exports.loadExternalPresetsFromDir=E,exports.loadOutputStylesFromSources=F,exports.parseOutputStyleFile=N,exports.partitionExternalPresets=l,exports.validateExternalPreset=T;

package/dist/node/index.d.cts

@@ -0,0 +1,255 @@
+import { ICreateSessionOptions } from "@robota-sdk/agent-framework";
+//#region src/preset-types.d.ts
+/**
+ * Effort dial passed through to the model invocation (mechanism, not persona text).
+ * `'xhigh'` corresponds to the long-running ("ultra") tier; `'high'` is the neutral default.
+ *
+ * Reuses the framework's `ICreateSessionOptions['effort']` channel (which is the
+ * `agent-core` `TModelEffort` SSOT) so a resolved preset effort threads straight to the
+ * provider invocation seam (PRESET-008) without introducing a parallel union.
+ */
+type TPresetEffort = NonNullable<ICreateSessionOptions['effort']>;
+/**
+ * Behavioural autonomy posture. Drives the permission posture (`permissionMode`) — it is a mechanism
+ * mapping, not a display label.
+ */
+type TPresetAutonomy = 'ask-first' | 'balanced' | 'act-first';
+/**
+ * Permission mode reused from the framework option SSOT (`ICreateSessionOptions`).
+ * Reusing the indexed access keeps a single source of truth for the permission-mode union.
+ */
+type TPresetPermissionMode = ICreateSessionOptions['permissionMode'];
+/**
+ * The framework-facing option subset a preset resolves into. Every field maps to an
+ * existing `agent-framework` session/assembly seam; presets never introduce new option types.
+ */
+interface IResolvedPresetOptions {
+  /**
+   * Portable persona/behaviour block (tone, refusal philosophy, output style, proactivity).
+   * Composed by the framework as a `source: 'persona'` system-prompt section (priority 5) —
+   * never runtime/tool/product-identity text. Empty/undefined adds no section (no regression).
+   */
+  persona?: string;
+  systemPrompt?: string;
+  appendSystemPrompt?: string;
+  agentName?: string;
+  model?: string;
+  language?: string;
+  effort?: TPresetEffort;
+  temperature?: number;
+  maxOutputTokens?: number;
+  /**
+   * Resolved framework permission-mode seam. The end value the assembly applies.
+   * Populated either directly, from `defaultPermissionMode`, or from the
+   * `autonomy` mapping (precedence: explicit `permissionMode` > `defaultPermissionMode`
+   * > `autonomy` mapping).
+   */
+  permissionMode?: TPresetPermissionMode;
+  /**
+   * Coarse permission posture declared by a preset. When set (and no explicit
+   * `permissionMode`), {@link resolvePreset} promotes it to `permissionMode`.
+   */
+  defaultPermissionMode?: TPresetPermissionMode;
+  allowedTools?: readonly string[];
+  deniedTools?: readonly string[];
+  enabledCommandModules?: readonly string[];
+  disabledCommandModules?: readonly string[];
+  enableParallelSubagents?: boolean;
+  selfVerification?: boolean;
+  autonomy?: TPresetAutonomy;
+}
+/**
+ * A named, pre-tuned bundle of framework option overrides plus display identity.
+ * Extends `IResolvedPresetOptions` (type SSOT) and adds the identity triple.
+ */
+interface IPreset extends IResolvedPresetOptions {
+  id: string;
+  title: string;
+  description: string;
+}
+//#endregion
+//#region src/output-style-types.d.ts
+type TOutputStyleSource = 'built-in' | 'managed' | 'user' | 'project';
+type TOutputStyleTokenCost = 'baseline' | 'low' | 'medium' | 'high' | 'unspecified';
+/** The provider-neutral response-shaping value carried into the framework prompt. */
+interface IOutputStyle {
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+  readonly instructions: string;
+  readonly keepCodingInstructions: boolean;
+  readonly tokenCost: TOutputStyleTokenCost;
+  readonly source: TOutputStyleSource;
+}
+/** Secret-free discovery projection used by command and UI surfaces. */
+type IOutputStyleSummary = Pick<IOutputStyle, 'id' | 'name' | 'description' | 'tokenCost' | 'source'>;
+interface IOutputStyleFile {
+  readonly fileName: string;
+  readonly content: string;
+}
+/** A source is already bounded by its owner; this package only decodes the supplied Markdown. */
+interface IOutputStyleSource {
+  readonly scope: Exclude<TOutputStyleSource, 'built-in'>;
+  readonly displayName: string;
+  /** Lower values are applied first. The last scope with an id wins. */
+  readonly precedence: number;
+  readonly files: readonly IOutputStyleFile[];
+}
+interface IOutputStyleLoadResult {
+  readonly styles: readonly IOutputStyle[];
+  readonly loaded: readonly string[];
+  readonly errors: readonly {
+    file: string;
+    error: string;
+  }[];
+}
+interface IOutputStyleRegistry {
+  listOutputStyles(): readonly IOutputStyleSummary[];
+  getOutputStyle(id: string): IOutputStyle | undefined;
+}
+//#endregion
+//#region src/presets/default.d.ts
+/**
+ * The neutral baseline preset. It carries NO option overrides so that resolving it is a
+ * pure no-op — applying `default` reproduces the standard agent behaviour exactly (no regression).
+ * The default agent identity is chosen by the product shell, not here,
+ * so that this preset stays a true identity element under merging.
+ */
+declare const defaultPreset: IPreset;
+//#endregion
+//#region src/presets/autonomous-builder.d.ts
+/**
+ * The first opinionated built-in preset: an autonomous, self-verifying builder posture.
+ *
+ * It both ships a portable persona block AND sets the framework/executor mechanism flags
+ * (`effort`, `autonomy`, `enableParallelSubagents`, `selfVerification`) so the style is backed
+ * by real, observable behaviour rather than persona text alone. The identifier is generic; the
+ * sourcing footnote in `description` is the only place a work-style attribution appears.
+ *
+ * For long-running tasks the effort dial may be raised to a higher tier; `'high'` is the
+ * neutral default carried here.
+ */
+declare const autonomousBuilderPreset: IPreset;
+//#endregion
+//#region src/resolve-preset.d.ts
+/** Lightweight `{ id, title, description }` view of a preset for discovery/UX. */
+interface IPresetSummary {
+  id: string;
+  title: string;
+  description: string;
+}
+/** Outcome of {@link partitionExternalPresets}: which presets were accepted and which rejected. */
+interface IPresetRegistrationResult {
+  accepted: readonly IPreset[];
+  rejected: readonly {
+    id: string;
+    reason: string;
+  }[];
+}
+/**
+ * Apply the external-preset conflict policy to one list, reading and mutating NOTHING outside it.
+ *
+ * Conflict policy: an external preset whose id matches a BUILT-IN preset is rejected
+ * (`'collides with built-in preset'`) — built-ins always win. An external preset whose id matches an
+ * earlier ACCEPTED external preset is rejected (`'duplicate preset id'`) — first one wins.
+ *
+ * ARCH-009. This is the whole of what the module-global registry used to be, minus the register:
+ * the policy was never the process's to hold, only the list it was applied to was. Both callers —
+ * {@link createPresetRegistry} and the external-preset loader — now pass their own list, so two
+ * products in one process cannot see each other's presets, and a repeated load cannot accumulate.
+ */
+declare function partitionExternalPresets(presets: readonly IPreset[]): IPresetRegistrationResult;
+/**
+ * Override layers for {@link resolvePreset}, in increasing precedence.
+ * `cliOverrides` model CLI flags; `explicit` models programmatic/SDK options.
+ */
+interface IResolvePresetContext {
+  cliOverrides?: IResolvedPresetOptions;
+  explicit?: IResolvedPresetOptions;
+}
+/**
+ * A per-call, instance-scoped preset registry (ARCH-005 R8) — since ARCH-009 the ONLY one there is.
+ *
+ * A registry holds its own merged list `[built-ins, ...accepted externals]`, so two products in one
+ * process do not share one and repeat construction does not accumulate. The
+ * `@robota-sdk/agent-product` assembler builds one per `assembleProduct` call and surfaces it on the
+ * command-host context, which is how `/preset` inside a live session reaches THIS product's presets
+ * rather than the process's.
+ */
+interface IPresetRegistry {
+  /** Resolve a preset id against this registry's presets. */
+  resolvePreset(id: string, context?: IResolvePresetContext): IResolvedPresetOptions;
+  /** Look up a preset by id within this registry, or `undefined`. */
+  getPreset(id: string): IPreset | undefined;
+  /** `{ id, title, description }` summaries of every preset in this registry. */
+  listPresets(): readonly IPresetSummary[];
+}
+/**
+ * Build an instance-scoped {@link IPresetRegistry} over `[built-ins, ...externalPresets]`.
+ *
+ * The conflict policy is {@link partitionExternalPresets}, applied to the argument list only: built-ins
+ * always win, and among the external presets the first one wins. No module-level state is read or
+ * mutated — this is a pure factory, and since ARCH-009 there is no module-level state to read.
+ *
+ * Called with no argument it is the BUILT-INS, which is the registry a host that supplies none gets.
+ */
+declare function createPresetRegistry(externalPresets?: readonly IPreset[]): IPresetRegistry;
+//#endregion
+//#region src/load-external-presets.d.ts
+/**
+ * Outcome of an external-preset load: the presets themselves, their ids, and per-file errors.
+ *
+ * ARCH-009 added `presets`. `loaded` used to be the only way out, because the presets went into a
+ * module-global registry and the caller read them back by id — which is what made the global
+ * load-bearing at startup. The caller now receives the values it loaded and builds its own registry
+ * over them, so nothing has to be looked up from process state.
+ */
+interface IExternalPresetLoadResult {
+  presets: readonly IPreset[];
+  loaded: readonly string[];
+  errors: readonly {
+    file: string;
+    error: string;
+  }[];
+}
+/**
+ * Load and validate every `*.json` external preset from `dir`.
+ *
+ * A missing directory yields an empty result (no error). Each file is JSON-parsed and validated;
+ * a parse or validation failure is recorded as a per-file error and skipped — the remaining files
+ * still load. The surviving presets go through {@link partitionExternalPresets}, whose rejections
+ * (built-in id collision or duplicate id) are folded into `errors` against their file.
+ *
+ * Loading REGISTERS NOTHING. The result is a value the caller owns.
+ */
+declare function loadExternalPresetsFromDir(dir: string): IExternalPresetLoadResult;
+//#endregion
+//#region src/preset-validation.d.ts
+/** Result of {@link validateExternalPreset}: the validated preset, or a single error message. */
+type TPresetValidationResult = {
+  ok: true;
+  preset: IPreset;
+} | {
+  ok: false;
+  error: string;
+};
+/**
+ * Manually validate an unknown value as an {@link IPreset} (no schema library).
+ *
+ * Required fields: non-empty `id`, `title`, `description` strings. Every other field is
+ * optional and is validated only when present; an unrecognised field is dropped (the built
+ * preset carries the recognised fields only, never unknown keys). On the first failed check
+ * returns `{ ok: false, error: '<field>: <reason>' }`.
+ */
+declare function validateExternalPreset(value: unknown): TPresetValidationResult;
+//#endregion
+//#region src/output-styles.d.ts
+declare const builtInOutputStyles: readonly IOutputStyle[];
+//#endregion
+//#region src/output-style-registry.d.ts
+declare function parseOutputStyleFile(file: IOutputStyleFile, source: TOutputStyleSource): IOutputStyle;
+declare function loadOutputStylesFromSources(sources: readonly IOutputStyleSource[]): IOutputStyleLoadResult;
+declare function createOutputStyleRegistry(sources?: readonly IOutputStyleSource[]): IOutputStyleRegistry;
+//#endregion
+export { type IExternalPresetLoadResult, type IOutputStyle, type IOutputStyleFile, type IOutputStyleLoadResult, type IOutputStyleRegistry, type IOutputStyleSource, type IOutputStyleSummary, type IPreset, type IPresetRegistrationResult, type IPresetRegistry, type IPresetSummary, type IResolvePresetContext, type IResolvedPresetOptions, type TOutputStyleSource, type TOutputStyleTokenCost, type TPresetAutonomy, type TPresetEffort, type TPresetPermissionMode, type TPresetValidationResult, autonomousBuilderPreset, builtInOutputStyles, createOutputStyleRegistry, createPresetRegistry, defaultPreset, loadExternalPresetsFromDir, loadOutputStylesFromSources, parseOutputStyleFile, partitionExternalPresets, validateExternalPreset };
+//# sourceMappingURL=index.d.cts.map

package/dist/node/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/preset-types.ts","../../src/output-style-types.ts","../../src/presets/default.ts","../../src/presets/autonomous-builder.ts","../../src/resolve-preset.ts","../../src/load-external-presets.ts","../../src/preset-validation.ts","../../src/output-styles.ts","../../src/output-style-registry.ts"],"mappings":";;;;;;;;;;KAUY,gBAAgB,YAAY;;;;;KAM5B;;;;;KAMA,wBAAwB;;;;;UAMnB;;;;;;EAOf;EACA;EACA;EACA;EAGA;EACA;EACA,SAAS;EACT;EACA;;;;;;;EASA,iBAAiB;;;;;EAKjB,wBAAwB;EACxB;EACA;EAGA;EACA;EAGA;EACA;EAGA,WAAW;;;;;;UAOI,gBAAgB;EAC/B;EACA;EACA;;;;KClFU;KAEA;;UAGK;WACN;WACA;WACA;WACA;WACA;WACA,WAAW;WACX,QAAQ;;;KAIP,sBAAsB,KAChC;UAIe;WACN;WACA;;;UAIM;WACN,OAAO,QAAQ;WACf;;WAEA;WACA,gBAAgB;;UAGV;WACN,iBAAiB;WACjB;WACA;IAAmB;IAAc;;;UAG3B;EACf,6BAA6B;EAC7B,eAAe,aAAa;;;;;;;;;;cCnCjB,eAAe;;;;;;;;;;;;;;cCsCf,yBAAyB;;;;UCXrB;EACf;EACA;EACA;;;UAIe;EACf,mBAAmB;EACnB;IAAqB;IAAY;;;;;;;;;;;;;;;iBAenB,yBAAyB,kBAAkB,YAAY;;;;;UAwBtD;EACf,eAAe;EACf,WAAW;;;;;;;;;;;UAuFI;;EAEf,cAAc,YAAY,UAAU,wBAAwB;;EAE5D,UAAU,aAAa;;EAEvB,wBAAwB;;;;;;;;;;;iBAYV,qBAAqB,2BAA0B,YAAiB;;;;;;;;;;;UC9K/D;EACf,kBAAkB;EAClB;EACA;IAAmB;IAAc;;;;;;;;;;;;;iBAanB,2BAA2B,cAAc;;;;KCtB7C;EAA4B;EAAU,QAAQ;;EAAc;EAAW;;;;;;;;;;iBAyKnE,uBAAuB,iBAAiB;;;cC/K3C,8BAA8B;;;iBCgF3B,qBACd,MAAM,kBACN,QAAQ,qBACP;iBA6Ca,4BACd,kBAAkB,uBACjB;iBA4Ca,0BACd,mBAAkB,uBACjB"}