@robota-sdk/agent-preset 3.0.0-beta.83 → 3.0.0-beta.84

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # @robota-sdk/agent-preset
 
+## 3.0.0-beta.84
+
+### Patch Changes
+
+- Updated dependencies [e8d70ac]
+  - @robota-sdk/agent-framework@3.0.0-beta.84
+
 ## 3.0.0-beta.83
 
 ### Patch Changes

package/README.md

@@ -1,67 +1,124 @@
-# Agent Preset
+# @robota-sdk/agent-preset
 
-Preset contract and resolver for the Robota SDK. A preset is a named, pre-tuned bundle of
-`agent-framework` option overrides (persona, model/effort, permission posture, command-module
-selection, execution capabilities, autonomy). This package owns the `IPreset` contract, the
-built-in `default` preset, and the instance-scoped registry that resolves them.
+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
+npm install @robota-sdk/agent-preset @robota-sdk/agent-framework
 ```
 
-## Public API
+Requires Node.js 22.12 or later.
+
+## Presets
 
 ```typescript
-import {
-  createPresetRegistry,
-  partitionExternalPresets,
-  defaultPreset,
-} from '@robota-sdk/agent-preset';
-import type {
-  IPreset,
-  IResolvedPresetOptions,
-  IPresetSummary,
-  IResolvePresetContext,
-} from '@robota-sdk/agent-preset';
-
-// A registry is per-call and holds its own list: `[built-ins, ...externalPresets]`. With no
-// argument it is the built-ins. Two registries in one process never see each other's presets.
+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 framework option overrides.
+// Resolve a preset into session option overrides.
 // Precedence (low → high): preset < cliOverrides < explicit.
-const options = registry.resolvePreset('default', {
+const options = registry.resolvePreset('careful-reviewer', {
   cliOverrides: { model: 'some-model' },
   explicit: { temperature: 0.2 },
 });
 
-// Discover presets for UX.
-const summaries = registry.listPresets(); // [{ id: 'default', title, description }, ...]
+// 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);
 ```
 
-The `default` preset carries no overrides, so resolving it is a pure no-op that reproduces the
-standard agent behaviour (no regression).
+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
 
-When migrating from the implicit Robota defaults, choose the agent name in your product and call
-`loadExternalPresetsFromDir(directory)` with a product-owned directory. The preset package no longer
-exports `DEFAULT_AGENT_NAME`, `defaultExternalPresetDir`, or the no-argument `loadExternalPresets`.
+| 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 |
 
-## Dependency Position
+`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);
 ```
-agent-framework        ← neutral assembly + option-type SSOT
+
+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 (preset contract + resolver)
+agent-preset      ← this package
     ↑
-agent-cli              ← consumes createPresetRegistry (per-call resolution, ARCH-008)
-agent-command          ← consumes the registry the HOST supplies, through the command-host adapters (ARCH-009)
+agent-cli, agent-command, agent-product   ← create registries and apply presets
 ```
 
-This package depends only on `@robota-sdk/agent-framework` and must not re-export it.
+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
 
-## Links
+## License
 
-- [npm](https://www.npmjs.com/package/@robota-sdk/agent-preset)
-- [GitHub](https://github.com/woojubb/robota)
+Robota is dual-licensed under the [GNU AGPL-3.0](../../LICENSE) or a [commercial license](../../COMMERCIAL.md). See [LICENSING.md](../../LICENSING.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@robota-sdk/agent-preset",
-  "version": "3.0.0-beta.83",
+  "version": "3.0.0-beta.84",
   "description": "Preset contract and resolver for the Robota SDK (IPreset, resolvePreset, listPresets, built-in presets)",
   "type": "module",
   "main": "dist/node/index.js",
@@ -33,9 +33,10 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/woojubb/robota.git"
+    "url": "https://github.com/woojubb/robota.git",
+    "directory": "packages/agent-preset"
   },
-  "homepage": "https://robota.io/",
+  "homepage": "https://docs.robota.io/en/packages/agent-preset/",
   "bugs": {
     "url": "https://github.com/woojubb/robota/issues"
   },
@@ -47,7 +48,7 @@
     "CHANGELOG.md"
   ],
   "dependencies": {
-    "@robota-sdk/agent-framework": "3.0.0-beta.83"
+    "@robota-sdk/agent-framework": "3.0.0-beta.84"
   },
   "devDependencies": {
     "rimraf": "^5.0.10",