@ai-outfitter/outfitter 0.3.0

package/LICENSE.md

@@ -0,0 +1,58 @@
+# Business Source License 1.1
+
+## Parameters
+
+**Licensor:** Unsupervised.com, Inc.
+
+**Licensed Work:** Outfitter
+
+The Licensed Work is © 2026 Unsupervised.com, Inc.
+
+**Additional Use Grant:** You may use the Licensed Work without a commercial license only when it is used with or for:
+
+- repositories that are publicly available under an open source license approved by the Open Source Initiative; or
+- repositories with fewer than 10 contributors.
+
+Use of the Licensed Work with or for a private repository with 10 or more contributors requires a commercial license from the Licensor.
+
+**Change Date:** 2030-01-14
+
+**Change License:** Apache License, Version 2.0
+
+---
+
+## License Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative works, redistribute, and make non-production use of the Licensed Work.
+The Licensor may make an Additional Use Grant, above, permitting limited production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly available distribution of a specific version of the Licensed Work under this License, whichever comes first, the Licensor hereby grants you rights under the terms of the Change License, and the rights granted in the paragraph above terminate.
+
+If your use of the Licensed Work does not comply with the requirements currently in effect as described in this License, you must purchase a commercial license from the Licensor, its affiliated entities, or authorized resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works of the Licensed Work, are subject to this License.
+This License applies separately for each version of the Licensed Work and the Change Date may vary for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy of the Licensed Work.
+If you receive the Licensed Work in original or modified form from a third party, the terms and conditions set forth in this License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically terminate your rights under this License for the current and all other versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of Licensor or its affiliates (provided that you may use a trademark or logo of Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON AN "AS IS" BASIS.
+LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS, EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND TITLE.
+
+---
+
+## Prohibited Uses
+
+You may not use the Licensed Work with or for a private repository with 10 or more contributors unless you have purchased a commercial license from the Licensor, its affiliated entities, or authorized resellers.
+
+For purposes of this License, a repository's contributor count is the number of people who have made commits or other accepted contributions to that repository, or who otherwise have permission to contribute code to that repository, whichever is greater.
+
+**Clarification**: This prohibition does not prevent you from using the Licensed Work without a commercial license with or for:
+
+- repositories that are publicly available under an open source license approved by the Open Source Initiative, regardless of contributor count;
+- private repositories with fewer than 10 contributors;
+- educational or research contexts that satisfy one of the preceding repository-use allowances.

package/README.md

@@ -0,0 +1,256 @@
+# outfitter
+
+`outfitter` is intended to be a management wrapper for launching [`pi`](https://github.com/earendil-works/pi-coding-agent) and Claude Code with configurable, reusable profiles.
+
+The goal is manageable agent CLI configuration:
+
+- Organizations can define standard pi or claude loadouts, share them, and launch agent CLIs consistently across different environments.
+- Individuals can swap between configurations of their coding agent, share those, and easily migrate to new machines.
+
+If you haven't tried [Pi](https://pi.dev) yet — we think it's a great coding harness & Outfitter is an easy way to try it.
+
+- Install and run `outfitter` to load pi with our standard configuration for engineers.
+
+## Install
+
+Install Outfitter globally from npm so the `outfitter` command is available on your PATH:
+
+```bash
+npm install -g @ai-outfitter/outfitter
+outfitter --help
+```
+
+Upgrade with:
+
+```bash
+npm update -g @ai-outfitter/outfitter
+```
+
+Use `npx` when you want to test Outfitter without adding a global command:
+
+```bash
+npx --yes @ai-outfitter/outfitter@latest --help
+```
+
+For source development, see [`CONTRIBUTING.md`](./CONTRIBUTING.md).
+
+Outfitter launches agent CLIs but does not install them.
+Install the agents you plan to use separately:
+
+- [pi](https://github.com/earendil-works/pi-coding-agent) — follow its installation instructions; the `pi` command must be on your PATH.
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) — only needed if you launch with `--agent claude`.
+
+## Why this exists
+
+Pi is highly configurable through settings directories, extensions, skills, prompts, themes, model settings, environment variables, and CLI flags.
+That flexibility is powerful, but businesses often need a higher-level control plane for repeatable deployments.
+
+`outfitter` should make it easy to answer questions like:
+
+- Which pi configuration should this employee or team use?
+- Which extensions, skills, prompts, models, and providers are approved?
+- Which credentials or environment variables should be present?
+- Should project-local `.pi` configuration be allowed, merged, or ignored?
+- How do we ship multiple standardized pi loadouts without manual setup?
+
+## Intended use case
+
+Example profile concepts:
+
+- `engineering-default` — standard engineering loadout with approved tools, prompts, and models.
+- `support` — customer-support-focused prompt and restricted tool set.
+- `sandbox` — isolated experimentation profile with disposable config and sessions.
+- `regulated` — locked-down profile with stricter extensions, context, and session behavior.
+
+A launch flow is intended to look like:
+
+```bash
+outfitter
+outfitter run --profile engineering-default
+outfitter run -p support -- --cwd ~/work/customer-issue
+outfitter sync
+outfitter setup
+outfitter setup https://github.com/my_account/outfitter_config
+outfitter welcome
+outfitter profile list
+outfitter profile create regulated --scope user
+```
+
+Under the hood, `outfitter` translates a selected profile into the selected agent launch environment.
+Pi runs use `PI_CODING_AGENT_DIR`; Claude Code runs use `CLAUDE_CONFIG_DIR`; both receive supported CLI flags, prompts, model settings, and environment variables.
+Select the adapter with `outfitter run --agent <pi|claude>`, or set `default_agent` in `settings.yml`.
+If neither is set, Outfitter defaults to pi for backward compatibility.
+If `outfitter` is run before `outfitter setup`, it creates the initial settings and default profile automatically before launching.
+When that first-run setup has an interactive terminal, Outfitter continues into the same welcome onboarding used by `outfitter welcome`.
+
+`outfitter welcome` explains Outfitter and Pi, asks you to choose an initial built-in role, and recommends a Pi productivity loadout.
+The current built-in role choices are `engineer` and `data_analyst`; Outfitter creates the selected local profile on the fly.
+The recommended loadout includes `ulta-tasklist`, `deepwork`, `pi-subagents`, and `pi-mcp-adapter`; you can accept it, choose individual items, or skip loadout installation.
+If you skip loadout installation, the generated profile has no extensions or skills.
+If Pi does not appear to be logged in after welcome onboarding, Outfitter opens Pi with `/login` automatically; outside welcome onboarding it prints a `/login` reminder instead.
+Outfitter never collects or persists provider API keys itself.
+
+`settings.yml` can point at local profiles, full Git URIs, or GitHub shorthand sources with optional refs and repository subpaths:
+
+```yaml
+remote_settings:
+  - github: my_account/outfitter_config
+    ref: main
+    path: settings.yml
+
+profile_sources:
+  - github: my_account/outfitter_config
+    ref: main
+    path: profiles
+```
+
+Run `outfitter sync` to fetch/update remote settings and profiles before using them.
+
+By default, Outfitter keeps reusable runtime cache files under `~/.outfitter/cache`.
+Set `cache_directory` in `settings.yml` to choose a different cache root; relative values resolve from the settings file that declares them.
+The pi adapter symlinks composite profile `utilities/` and `bin/` paths into this cache so pi-managed utilities such as `fd` and `rg` survive across temporary composite profile directories.
+
+Settings can also define arbitrary nested `custom_settings` values for Outfitter-time composite profile templating:
+
+```yaml
+custom_settings:
+  build_commands:
+    lint: npm run lint
+```
+
+Generated composite profile files can reference them with Outfitter's LiquidJS-based custom delimiters:
+
+```yaml
+command: '[[= outfitter.custom_settings.build_commands.lint ]]'
+```
+
+Control tags use `[[% ... %]]`, for example `[[% for item in outfitter.custom_settings.items %]]`.
+Outfitter intentionally does not use common `{{ ... }}` delimiters, and plain shell expressions like `[[ -f package.json ]]` are left alone.
+
+## Setup from a settings repository
+
+You can bootstrap a machine from a Git repository:
+
+```bash
+outfitter setup https://github.com/my_account/outfitter_config
+```
+
+`outfitter setup` requires an interactive terminal on both stdin and stdout.
+When a repository is provided, it clones or updates the repository in Outfitter's shared repository cache, then uses it as a non-overwriting starting point:
+
+- if `~/.outfitter/settings.yml` does not exist, Outfitter copies the starter `settings.yml`;
+- if starter profiles exist, Outfitter copies missing profile files into `~/.outfitter/profiles/`;
+- existing user settings and profile files are otherwise left unchanged;
+- after setup, Outfitter runs the same sync behavior used by `outfitter sync`;
+- on initial interactive first-run setup, Outfitter skips the older default-profile prompt and lets welcome onboarding choose the generated local default profile;
+- outside that initial welcome handoff, Outfitter shows a short setup wizard that lists synced profiles and writes the selected default profile to user settings;
+- interactive setup continues into welcome onboarding to record role and loadout choices.
+
+A setup repository can use either root-level Outfitter files:
+
+```text
+outfitter_config/
+  settings.yml
+  profiles/
+    engineering-default/
+      profile.yml
+    support/
+      profile.yml
+```
+
+or a `.outfitter/` layout:
+
+```text
+outfitter_config/
+  .outfitter/
+    settings.yml
+    profiles/
+      engineering-default/
+        profile.yml
+      support/
+        profile.yml
+```
+
+Example `settings.yml` for a setup repository:
+
+```yaml
+default_profile: engineering-default
+
+profile_sources:
+  - path: ./profiles
+
+  # Optional: keep loading future updates from this same repo.
+  - github: my_account/outfitter_config
+    ref: main
+    path: profiles
+```
+
+If you want ongoing centralized settings, use a small local `~/.outfitter/settings.yml` that points at remote settings:
+
+```yaml
+remote_settings:
+  - github: my_account/outfitter_config
+    ref: main
+    path: settings.yml
+```
+
+Then run:
+
+```bash
+outfitter sync
+```
+
+## Profile model sketch
+
+A profile will use YAML.
+An initial profile shape is:
+
+```yaml
+id: engineering-default
+label: Engineering Default
+inherits:
+  - base-typescript
+
+controls:
+  model: anthropic/claude-sonnet-4
+  environment:
+    TEAM_MODE: engineering
+```
+
+The exact stable schema is governed by the requirements in `requirements/` and the JSON Schema files in `src/schemas/`, which are still expected to evolve with implementation.
+
+Pi profiles can also ship DeepWork jobs for that profile under `cli_specific/pi/deepwork/jobs/`.
+When Outfitter launches Pi, it adds contributing profile job folders to `DEEPWORK_ADDITIONAL_JOBS_FOLDERS` so the DeepWork frontend can discover profile-owned workflows without copying them into a project `.deepwork/jobs/` directory.
+By default, profiles with bundled jobs receive only their profile-bundled jobs; set `controls.pi.allow_external_deepwork_jobs: true` to also include inherited `DEEPWORK_ADDITIONAL_JOBS_FOLDERS` entries.
+
+## Design direction
+
+The current recommendation is to build `outfitter` around pi's existing native configuration mechanisms:
+
+1. Use a temporary composite profile directory as `PI_CODING_AGENT_DIR` for each run.
+2. Persist intentional pi state through adapter-declared symlinks to profile, native pi, or Outfitter cache files.
+   Native pi fallback is only a durable target for declared state symlinks; it is not an inherited base profile layer.
+3. Layer profile-controlled environment variables and pi CLI flags on top.
+4. Use explicit `--extension` / `-e` injection for bootstrap behavior that needs to run inside pi.
+5. Decide per profile whether project-local `.pi` overrides are allowed.
+6. Keep the wrapper responsible for anything that must happen before pi starts, such as selecting config directories, setting credentials, or choosing session locations.
+
+See [`recommendation.md`](./recommendation.md) for current notes on pi startup behavior and wrapper strategy.
+
+## Status
+
+This repository is under phased implementation.
+
+A minimal executable CLI exists, with initial settings/profile schemas, local and URI-backed profile loading, profile resolution internals, first-pass `setup`, `sync`, `profile list`, and `profile create` commands, and a first-pass `run` command for assembling a temporary composite profile and launching pi or Claude Code.
+Stable end-to-end pi launch behavior and user-facing examples will be hardened in a later phase.
+The initial dependency and architecture decisions are documented in `package.json`, `doc/architecture.md`, and `requirements/`.
+
+## Future work
+
+- Define a stable profile schema.
+- Decide where organization-managed profiles are discovered from.
+- Harden stable `outfitter run --profile <profile>` behavior.
+- Add validation and inspection commands.
+- Expand user-facing documentation for resolved profile inheritance and composition.
+- Add locking / policy controls for business-managed environments.
+- Add examples for common organizational deployments.

package/dist/agents/AdapterProfileControls.d.ts

@@ -0,0 +1,20 @@
+import type { ProfileControls } from '../profiles/Profile.js';
+export declare const genericControlNames: Set<string>;
+export declare const supportedControlNames: (controls: ReadonlySet<string>) => readonly string[];
+export declare const controlAliases: readonly [{
+    readonly camelCase: "sessionDirectory";
+    readonly snakeCase: "session_directory";
+}, {
+    readonly camelCase: "promptTemplate";
+    readonly snakeCase: "prompt_template";
+}, {
+    readonly camelCase: "systemPrompt";
+    readonly snakeCase: "system_prompt";
+}, {
+    readonly camelCase: "appendSystemPrompt";
+    readonly snakeCase: "append_system_prompt";
+}];
+export declare const mergeAgentSpecificControls: <T extends ProfileControls>(controls: ProfileControls, agentKey: "pi" | "claude") => T;
+export declare const flagValue: (flag: string, value: string | undefined) => readonly string[];
+export declare const repeatFlag: (flag: string, values: readonly string[] | undefined) => readonly string[];
+export declare const findUnsupportedControlNames: (controls: Readonly<Record<string, unknown>>, supportedControls: ReadonlySet<string>, knownControls?: ReadonlySet<string>) => string[];

package/dist/agents/AdapterProfileControls.js

@@ -0,0 +1,63 @@
+import { mergeLaunchResourceSources } from './LaunchResources.js';
+export const genericControlNames = new Set([
+    'model',
+    'provider',
+    'thinking',
+    'environment',
+    'args',
+    'sessionDirectory',
+    'session_directory',
+    'extensions',
+    'skills',
+    'promptTemplate',
+    'prompt_template',
+    'systemPrompt',
+    'system_prompt',
+    'appendSystemPrompt',
+    'append_system_prompt',
+    'pi',
+    'claude',
+]);
+export const supportedControlNames = (controls) => [...controls].filter((controlName) => !controlName.includes('_') && controlName !== 'pi' && controlName !== 'claude');
+export const controlAliases = [
+    { camelCase: 'sessionDirectory', snakeCase: 'session_directory' },
+    { camelCase: 'promptTemplate', snakeCase: 'prompt_template' },
+    { camelCase: 'systemPrompt', snakeCase: 'system_prompt' },
+    { camelCase: 'appendSystemPrompt', snakeCase: 'append_system_prompt' },
+];
+export const mergeAgentSpecificControls = (controls, agentKey) => {
+    const agentControls = controls[agentKey];
+    return {
+        ...controls,
+        ...definedControls(agentControls),
+        environment: { ...controls.environment, ...agentControls?.environment },
+        args: agentControls?.args ?? controls.args,
+        extensions: mergeLaunchResourceSources('extension', controls.extensions, agentControls?.extensions),
+        skills: mergeLaunchResourceSources('skill', controls.skills, agentControls?.skills),
+    };
+};
+export const flagValue = (flag, value) => value === undefined ? [] : [flag, value];
+export const repeatFlag = (flag, values) => values === undefined ? [] : values.flatMap((value) => [flag, value]);
+export const findUnsupportedControlNames = (controls, supportedControls, knownControls = genericControlNames) => {
+    const controlNames = new Set(Object.keys(controls));
+    const unsupported = [];
+    for (const { camelCase, snakeCase } of controlAliases) {
+        if (!controlNames.has(camelCase) && !controlNames.has(snakeCase)) {
+            continue;
+        }
+        if (!supportedControls.has(camelCase) && !supportedControls.has(snakeCase)) {
+            unsupported.push(controlNames.has(snakeCase) ? snakeCase : camelCase);
+        }
+        controlNames.delete(camelCase);
+        controlNames.delete(snakeCase);
+    }
+    unsupported.push(...[...controlNames].filter((controlName) => !knownControls.has(controlName) || !supportedControls.has(controlName)));
+    return unsupported;
+};
+const definedControls = (controls) => {
+    if (controls === undefined) {
+        return {};
+    }
+    return Object.fromEntries(Object.entries(controls).filter((entry) => entry[1] !== undefined));
+};
+//# sourceMappingURL=AdapterProfileControls.js.map

package/dist/agents/AdapterProfileControls.js.map

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

package/dist/agents/AdapterStatePaths.d.ts

@@ -0,0 +1,12 @@
+import type { Profile } from '../profiles/Profile.js';
+import type { StatePathDeclaration, StatePersistenceStrategy, CompositeProfileStatePath } from '../compositeProfile/StatePersistence.js';
+export interface DeclaredStatePathInput {
+    readonly adapterId: string;
+    readonly declarations: Readonly<Record<string, StatePathDeclaration>>;
+    readonly profile: Profile;
+    readonly resolveSourcePath: (relativePath: string, directory: boolean) => string;
+}
+export declare const createDeclaredStatePaths: (input: DeclaredStatePathInput) => readonly CompositeProfileStatePath[];
+export declare const assertDeclaredStatePersistenceKeys: (adapterId: string, declarations: Readonly<Record<string, StatePathDeclaration>>, profile: Profile) => void;
+export declare const resolveStateStrategy: (profile: Profile, relativePath: string, declaration: StatePathDeclaration) => StatePersistenceStrategy;
+export declare const findProfileStateSource: (profileFolders: readonly string[], adapterId: string, relativePath: string, directory: boolean) => string | undefined;

package/dist/agents/AdapterStatePaths.js

@@ -0,0 +1,44 @@
+// Shared helpers for adapter-declared composite profile state paths.
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+export const createDeclaredStatePaths = (input) => {
+    assertDeclaredStatePersistenceKeys(input.adapterId, input.declarations, input.profile);
+    return Object.entries(input.declarations).map(([relativePath, declaration]) => {
+        const strategy = resolveStateStrategy(input.profile, relativePath, declaration);
+        const directory = relativePath.endsWith('/');
+        return {
+            relativePath,
+            strategy,
+            directory,
+            sourcePath: strategy === 'symlink' && relativePath !== 'unknown'
+                ? input.resolveSourcePath(relativePath, directory)
+                : undefined,
+        };
+    });
+};
+export const assertDeclaredStatePersistenceKeys = (adapterId, declarations, profile) => {
+    for (const relativePath of Object.keys(profile.statePersistence ?? {})) {
+        if (!Object.hasOwn(declarations, relativePath)) {
+            throw new Error(`state_persistence path '${relativePath}' is not declared by the ${adapterId} adapter`);
+        }
+    }
+};
+export const resolveStateStrategy = (profile, relativePath, declaration) => {
+    const strategy = profile.statePersistence?.[relativePath] ?? declaration.defaultStrategy;
+    /* v8 ignore next -- Adapter declarations define defaults; this guards future declaration regressions. */
+    if (strategy === undefined) {
+        throw new Error(`missing state_persistence strategy for "${relativePath}"`);
+    }
+    if (!declaration.allowedStrategies.includes(strategy)) {
+        throw new Error(`state_persistence strategy '${strategy}' is not allowed for "${relativePath}"`);
+    }
+    return strategy;
+};
+export const findProfileStateSource = (profileFolders, adapterId, relativePath, directory) => {
+    const normalizedRelativePath = directory ? relativePath.slice(0, -1) : relativePath;
+    return [...profileFolders]
+        .reverse()
+        .map((profileFolder) => join(profileFolder, 'cli_specific', adapterId, normalizedRelativePath))
+        .find((candidate) => existsSync(candidate));
+};
+//# sourceMappingURL=AdapterStatePaths.js.map

package/dist/agents/AdapterStatePaths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AdapterStatePaths.js","sourceRoot":"","sources":["../../src/agents/AdapterStatePaths.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAgBjC,MAAM,CAAC,MAAM,wBAAwB,GAAG,CAAC,KAA6B,EAAwC,EAAE;IAC9G,kCAAkC,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,YAAY,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IAEvF,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,EAAE,WAAW,CAAC,EAAE,EAAE;QAC5E,MAAM,QAAQ,GAAG,oBAAoB,CAAC,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,WAAW,CAAC,CAAC;QAChF,MAAM,SAAS,GAAG,YAAY,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QAE7C,OAAO;YACL,YAAY;YACZ,QAAQ;YACR,SAAS;YACT,UAAU,EACR,QAAQ,KAAK,SAAS,IAAI,YAAY,KAAK,SAAS;gBAClD,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,YAAY,EAAE,SAAS,CAAC;gBAClD,CAAC,CAAC,SAAS;SAChB,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,kCAAkC,GAAG,CAChD,SAAiB,EACjB,YAA4D,EAC5D,OAAgB,EACV,EAAE;IACR,KAAK,MAAM,YAAY,IAAI,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,gBAAgB,IAAI,EAAE,CAAC,EAAE,CAAC;QACvE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,YAAY,EAAE,YAAY,CAAC,EAAE,CAAC;YAC/C,MAAM,IAAI,KAAK,CAAC,2BAA2B,YAAY,4BAA4B,SAAS,UAAU,CAAC,CAAC;QAC1G,CAAC;IACH,CAAC;AACH,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAClC,OAAgB,EAChB,YAAoB,EACpB,WAAiC,EACP,EAAE;IAC5B,MAAM,QAAQ,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,YAAY,CAAC,IAAI,WAAW,CAAC,eAAe,CAAC;IAEzF,yGAAyG;IACzG,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,2CAA2C,YAAY,GAAG,CAAC,CAAC;IAC9E,CAAC;IAED,IAAI,CAAC,WAAW,CAAC,iBAAiB,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,KAAK,CAAC,+BAA+B,QAAQ,yBAAyB,YAAY,GAAG,CAAC,CAAC;IACnG,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAAG,CACpC,cAAiC,EACjC,SAAiB,EACjB,YAAoB,EACpB,SAAkB,EACE,EAAE;IACtB,MAAM,sBAAsB,GAAG,SAAS,CAAC,CAAC,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC;IAEpF,OAAO,CAAC,GAAG,cAAc,CAAC;SACvB,OAAO,EAAE;SACT,GAAG,CAAC,CAAC,aAAa,EAAE,EAAE,CAAC,IAAI,CAAC,aAAa,EAAE,cAAc,EAAE,SAAS,EAAE,sBAAsB,CAAC,CAAC;SAC9F,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;AAChD,CAAC,CAAC"}

package/dist/agents/AgentAdapter.d.ts

@@ -0,0 +1,32 @@
+import type { Profile } from '../profiles/Profile.js';
+import type { Settings } from '../settings/Settings.js';
+import type { StatePathDeclaration } from '../compositeProfile/StatePersistence.js';
+import type { CompositeProfile } from '../compositeProfile/CompositeProfile.js';
+export interface AgentLaunchPlan {
+    readonly command: string;
+    readonly args: readonly string[];
+    readonly env: Readonly<Record<string, string>>;
+}
+export interface AgentLaunchContext {
+    readonly profileFolders?: readonly string[];
+}
+export interface AgentCompositeProfilePlan {
+    readonly compositeProfile: CompositeProfile;
+    readonly warnings: readonly string[];
+}
+export interface AgentAdapter {
+    readonly id: string;
+    readonly supportedControls: readonly string[];
+    readonly statePaths?: Readonly<Record<string, StatePathDeclaration>>;
+    createCompositeProfile(profile: Profile, input: {
+        readonly rootDirectory: string;
+        readonly profilePaths: readonly string[];
+        readonly profileFolders?: readonly string[];
+        readonly homeDirectory?: string;
+        readonly cacheDirectory?: string;
+        readonly settings?: Settings;
+        readonly projectDirectory?: string;
+    }): AgentCompositeProfilePlan;
+    createLaunchPlan(compositeProfile: CompositeProfile, profile?: Profile, passThroughArgs?: readonly string[], context?: AgentLaunchContext): AgentLaunchPlan;
+    getUnsupportedControls(profile: Profile): readonly string[];
+}

package/dist/agents/AgentAdapter.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=AgentAdapter.js.map

package/dist/agents/AgentAdapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentAdapter.js","sourceRoot":"","sources":["../../src/agents/AgentAdapter.ts"],"names":[],"mappings":""}

package/dist/agents/AgentRegistry.d.ts

@@ -0,0 +1,6 @@
+import type { AgentAdapter } from './AgentAdapter.js';
+export type SupportedAgentId = 'pi' | 'claude';
+export declare const defaultAgentId: SupportedAgentId;
+export declare const supportedAgentIds: readonly ["pi", "claude"];
+export declare const isSupportedAgentId: (agentId: string) => agentId is SupportedAgentId;
+export declare const createAgentAdapter: (agentId: string | undefined) => AgentAdapter;

package/dist/agents/AgentRegistry.js

@@ -0,0 +1,17 @@
+import { createClaudeAdapter } from './claude/ClaudeAdapter.js';
+import { createPiAdapter } from './pi/PiAdapter.js';
+export const defaultAgentId = 'pi';
+export const supportedAgentIds = [defaultAgentId, 'claude'];
+export const isSupportedAgentId = (agentId) => supportedAgentIds.includes(agentId);
+export const createAgentAdapter = (agentId) => {
+    const selectedAgentId = agentId ?? defaultAgentId;
+    switch (selectedAgentId) {
+        case 'pi':
+            return createPiAdapter();
+        case 'claude':
+            return createClaudeAdapter();
+        default:
+            throw new Error(`Unknown agent '${selectedAgentId}'. Expected one of: ${supportedAgentIds.join(', ')}.`);
+    }
+};
+//# sourceMappingURL=AgentRegistry.js.map

package/dist/agents/AgentRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentRegistry.js","sourceRoot":"","sources":["../../src/agents/AgentRegistry.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAIpD,MAAM,CAAC,MAAM,cAAc,GAAqB,IAAI,CAAC;AAErD,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,cAAc,EAAE,QAAQ,CAAgD,CAAC;AAE3G,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,OAAe,EAA+B,EAAE,CACjF,iBAAiB,CAAC,QAAQ,CAAC,OAA2B,CAAC,CAAC;AAE1D,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,OAA2B,EAAgB,EAAE;IAC9E,MAAM,eAAe,GAAG,OAAO,IAAI,cAAc,CAAC;IAElD,QAAQ,eAAe,EAAE,CAAC;QACxB,KAAK,IAAI;YACP,OAAO,eAAe,EAAE,CAAC;QAC3B,KAAK,QAAQ;YACX,OAAO,mBAAmB,EAAE,CAAC;QAC/B;YACE,MAAM,IAAI,KAAK,CAAC,kBAAkB,eAAe,uBAAuB,iBAAiB,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IAC7G,CAAC;AACH,CAAC,CAAC"}

package/dist/agents/LaunchResources.d.ts

@@ -0,0 +1,13 @@
+export type LaunchResourceKind = 'extension' | 'skill';
+export type LaunchResourceOrigin = 'generic-controls' | 'agent-controls' | 'profile-controls' | 'settings';
+export interface LaunchResourceEntry {
+    readonly kind: LaunchResourceKind;
+    readonly source: string;
+    readonly identity: string;
+    readonly origin: LaunchResourceOrigin;
+    /** Higher values win ties for the same identity. */
+    readonly precedence: number;
+}
+export declare const createLaunchResourceEntries: (kind: LaunchResourceKind, sources: readonly string[] | undefined, origin: LaunchResourceOrigin, precedence: number) => readonly LaunchResourceEntry[];
+export declare const mergeLaunchResourceEntries: (entries: readonly LaunchResourceEntry[]) => readonly LaunchResourceEntry[];
+export declare const mergeLaunchResourceSources: (kind: LaunchResourceKind, lowerPrecedence: readonly string[] | undefined, higherPrecedence: readonly string[] | undefined) => readonly string[] | undefined;

package/dist/agents/LaunchResources.js

@@ -0,0 +1,35 @@
+// Models launch inputs as precedence-bearing resources that can be merged and deduplicated.
+import { normalizeExtensionResourceIdentity, normalizeLaunchResourceIdentity } from './ResourceIdentity.js';
+export const createLaunchResourceEntries = (kind, sources = [], origin, precedence) => sources.map((source) => ({
+    kind,
+    source,
+    identity: createLaunchResourceIdentity(kind, source),
+    origin,
+    precedence,
+}));
+export const mergeLaunchResourceEntries = (entries) => {
+    const entriesByIdentity = new Map();
+    for (const entry of entries) {
+        const existing = entriesByIdentity.get(entry.identity);
+        if (existing === undefined || entry.precedence > existing.precedence) {
+            entriesByIdentity.set(entry.identity, entry);
+        }
+    }
+    return entries.filter((entry) => entriesByIdentity.get(entry.identity) === entry);
+};
+export const mergeLaunchResourceSources = (kind, lowerPrecedence, higherPrecedence) => {
+    if (lowerPrecedence === undefined && higherPrecedence === undefined) {
+        return undefined;
+    }
+    return mergeLaunchResourceEntries([
+        ...createLaunchResourceEntries(kind, higherPrecedence, 'agent-controls', 1),
+        ...createLaunchResourceEntries(kind, lowerPrecedence, 'generic-controls', 0),
+    ]).map((entry) => entry.source);
+};
+const createLaunchResourceIdentity = (kind, source) => {
+    if (kind === 'extension') {
+        return normalizeExtensionResourceIdentity(source);
+    }
+    return normalizeLaunchResourceIdentity(source);
+};
+//# sourceMappingURL=LaunchResources.js.map

package/dist/agents/LaunchResources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LaunchResources.js","sourceRoot":"","sources":["../../src/agents/LaunchResources.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,OAAO,EAAE,kCAAkC,EAAE,+BAA+B,EAAE,MAAM,uBAAuB,CAAC;AAc5G,MAAM,CAAC,MAAM,2BAA2B,GAAG,CACzC,IAAwB,EACxB,UAA6B,EAAE,EAC/B,MAA4B,EAC5B,UAAkB,EACc,EAAE,CAClC,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACvB,IAAI;IACJ,MAAM;IACN,QAAQ,EAAE,4BAA4B,CAAC,IAAI,EAAE,MAAM,CAAC;IACpD,MAAM;IACN,UAAU;CACX,CAAC,CAAC,CAAC;AAEN,MAAM,CAAC,MAAM,0BAA0B,GAAG,CAAC,OAAuC,EAAkC,EAAE;IACpH,MAAM,iBAAiB,GAAG,IAAI,GAAG,EAA+B,CAAC;IAEjE,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;QAC5B,MAAM,QAAQ,GAAG,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;QAEvD,IAAI,QAAQ,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,GAAG,QAAQ,CAAC,UAAU,EAAE,CAAC;YACrE,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QAC/C,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,iBAAiB,CAAC,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,KAAK,KAAK,CAAC,CAAC;AACpF,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,0BAA0B,GAAG,CACxC,IAAwB,EACxB,eAA8C,EAC9C,gBAA+C,EAChB,EAAE;IACjC,IAAI,eAAe,KAAK,SAAS,IAAI,gBAAgB,KAAK,SAAS,EAAE,CAAC;QACpE,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,0BAA0B,CAAC;QAChC,GAAG,2BAA2B,CAAC,IAAI,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,CAAC,CAAC;QAC3E,GAAG,2BAA2B,CAAC,IAAI,EAAE,eAAe,EAAE,kBAAkB,EAAE,CAAC,CAAC;KAC7E,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;AAClC,CAAC,CAAC;AAEF,MAAM,4BAA4B,GAAG,CAAC,IAAwB,EAAE,MAAc,EAAU,EAAE;IACxF,IAAI,IAAI,KAAK,WAAW,EAAE,CAAC;QACzB,OAAO,kCAAkC,CAAC,MAAM,CAAC,CAAC;IACpD,CAAC;IAED,OAAO,+BAA+B,CAAC,MAAM,CAAC,CAAC;AACjD,CAAC,CAAC"}

package/dist/agents/ResourceIdentity.d.ts

@@ -0,0 +1,2 @@
+export declare const normalizeExtensionResourceIdentity: (source: string) => string;
+export declare const normalizeLaunchResourceIdentity: (source: string) => string;