@praxis-ai/praxis 0.1.0 → 0.1.2

package/dist/toolBase/profiles.js

@@ -0,0 +1,95 @@
+export const MINIMAL_CODING_TOOL_IDS = [
+    "shell.run",
+    "file.read",
+    "file.search",
+    "patch.apply",
+    "plan.update",
+    "user.ask",
+];
+export const STANDARD_AGENT_TOOL_IDS = [
+    ...MINIMAL_CODING_TOOL_IDS,
+    "web.search",
+    "web.fetch",
+    "skill.load",
+    "mcp.use",
+    "agent.spawn",
+];
+export const EXTENDED_AGENT_TOOL_IDS = [
+    ...STANDARD_AGENT_TOOL_IDS,
+    "file.write",
+    "file.edit",
+    "agent.message",
+    "agent.wait",
+    "context.load",
+    "mcp.resources",
+    "lsp.query",
+    "browser.use",
+    "computer.use",
+    "image.view",
+    "image.generate",
+    "audio.transcribe",
+    "media.generate",
+    "memory.use",
+    "repo.inspect",
+];
+export const TOOL_BASE_PROFILES = [
+    {
+        name: "minimalCoding",
+        description: "Pi/Codex-like small coding set for models that perform best with a short familiar tool list.",
+        defaultVisibility: "model",
+        toolIds: MINIMAL_CODING_TOOL_IDS,
+        hiddenToolIds: [],
+        deferredToolIds: [],
+    },
+    {
+        name: "standardAgent",
+        description: "Default Praxis model-facing set: coding, grounding, skill, MCP, and subagent delegation.",
+        defaultVisibility: "model",
+        toolIds: STANDARD_AGENT_TOOL_IDS,
+        hiddenToolIds: [],
+        deferredToolIds: [],
+    },
+    {
+        name: "extendedAgent",
+        description: "Large set for high-capability runtimes; uncommon tools remain deferred until the agent asks for them.",
+        defaultVisibility: "deferred",
+        toolIds: EXTENDED_AGENT_TOOL_IDS,
+        hiddenToolIds: [],
+        deferredToolIds: [
+            "file.write",
+            "file.edit",
+            "agent.message",
+            "agent.wait",
+            "context.load",
+            "mcp.resources",
+            "lsp.query",
+            "browser.use",
+            "computer.use",
+            "image.view",
+            "image.generate",
+            "audio.transcribe",
+            "media.generate",
+            "memory.use",
+            "repo.inspect",
+        ],
+    },
+    {
+        name: "runtimeOnly",
+        description: "Runtime governance ports and internal operations; never sent directly to the model.",
+        defaultVisibility: "runtime",
+        toolIds: [],
+        hiddenToolIds: [
+            "approval.request",
+            "permission.check",
+            "sandbox.run",
+            "artifact.store",
+            "output.truncate",
+            "process.wait",
+            "process.kill",
+            "secret.resolve",
+            "tool.discover",
+            "tool.describe",
+        ],
+        deferredToolIds: [],
+    },
+];

package/dist/toolBase/providerBridge.d.ts

@@ -0,0 +1,16 @@
+import type { ToolBaseDefinition, ToolBaseProviderCapability } from "./types.js";
+export type ProviderNeutralToolSpec = {
+    name: string;
+    description: string;
+    inputSchema: Readonly<Record<string, unknown>>;
+    metadata: Readonly<{
+        praxisToolId: string;
+        risk: string;
+        layer: string;
+        interaction: string;
+    }>;
+};
+export declare function toProviderNeutralToolSpec(definition: ToolBaseDefinition, provider?: ToolBaseProviderCapability): ProviderNeutralToolSpec;
+export declare function toProviderNeutralToolSpecs(definitions: readonly ToolBaseDefinition[], provider?: ToolBaseProviderCapability): readonly ProviderNeutralToolSpec[];
+export declare function encodeProviderToolName(toolId: string): string;
+export declare function decodeProviderToolName(name: string): string;

package/dist/toolBase/providerBridge.js

@@ -0,0 +1,31 @@
+export function toProviderNeutralToolSpec(definition, provider) {
+    return {
+        name: encodeProviderToolName(definition.id),
+        description: definition.description,
+        inputSchema: adaptSchemaForProvider(definition.inputSchema, provider),
+        metadata: {
+            praxisToolId: definition.id,
+            risk: definition.risk,
+            layer: definition.layer,
+            interaction: definition.interaction,
+        },
+    };
+}
+export function toProviderNeutralToolSpecs(definitions, provider) {
+    return definitions.map((definition) => toProviderNeutralToolSpec(definition, provider));
+}
+export function encodeProviderToolName(toolId) {
+    return toolId.replaceAll(".", "__");
+}
+export function decodeProviderToolName(name) {
+    return name.replaceAll("__", ".");
+}
+function adaptSchemaForProvider(schema, provider) {
+    if (provider?.supportsStrictJsonSchema !== false) {
+        return schema;
+    }
+    return {
+        ...schema,
+        additionalProperties: true,
+    };
+}

package/dist/toolBase/registry.d.ts

@@ -0,0 +1,14 @@
+import type { ToolBaseDefinition, ToolBaseId, ToolBaseProfile, ToolBaseProfileName, ToolBaseProviderCapability, ToolBaseToolSet } from "./types.js";
+export type CreateToolBaseRegistryOptions = {
+    catalog?: readonly ToolBaseDefinition[];
+    profiles?: readonly ToolBaseProfile[];
+};
+export type ToolBaseRegistry = {
+    listDefinitions(): readonly ToolBaseDefinition[];
+    listProfiles(): readonly ToolBaseProfile[];
+    getDefinition(toolId: ToolBaseId): ToolBaseDefinition | undefined;
+    getProfile(profile: ToolBaseProfileName): ToolBaseProfile | undefined;
+    resolveToolSet(profile: ToolBaseProfileName, provider?: ToolBaseProviderCapability): ToolBaseToolSet;
+};
+export declare function createToolBaseRegistry(options?: CreateToolBaseRegistryOptions): ToolBaseRegistry;
+export declare const defaultToolBaseRegistry: ToolBaseRegistry;

package/dist/toolBase/registry.js

@@ -0,0 +1,97 @@
+import { TOOL_BASE_CATALOG } from "./catalog.js";
+import { TOOL_BASE_PROFILES } from "./profiles.js";
+export function createToolBaseRegistry(options = {}) {
+    const catalog = options.catalog ?? TOOL_BASE_CATALOG;
+    const profiles = options.profiles ?? TOOL_BASE_PROFILES;
+    const definitionById = new Map(catalog.map((definition) => [definition.id, definition]));
+    const profileByName = new Map(profiles.map((profile) => [profile.name, profile]));
+    return {
+        listDefinitions: () => catalog,
+        listProfiles: () => profiles,
+        getDefinition: (toolId) => definitionById.get(toolId),
+        getProfile: (profile) => profileByName.get(profile),
+        resolveToolSet: (profileName, provider) => {
+            const profile = profileByName.get(profileName) ?? profileByName.get("standardAgent");
+            if (profile === undefined) {
+                return emptyToolSet(profileName);
+            }
+            return resolveToolSetFromProfile(profile, definitionById, provider);
+        },
+    };
+}
+function resolveToolSetFromProfile(profile, definitionById, provider) {
+    const deferredIds = new Set(profile.deferredToolIds ?? []);
+    const hiddenIds = new Set(profile.hiddenToolIds ?? []);
+    const maxVisibleTools = provider?.maxVisibleTools;
+    const visible = [];
+    const deferred = [];
+    const runtimeOnly = [];
+    const disabled = [];
+    for (const toolId of profile.toolIds) {
+        const definition = definitionById.get(toolId);
+        if (definition === undefined) {
+            disabled.push(missingToolDefinition(toolId));
+            continue;
+        }
+        const visibility = resolveVisibility(definition, deferredIds, hiddenIds);
+        if (visibility === "runtime") {
+            runtimeOnly.push(definition);
+        }
+        else if (visibility === "deferred") {
+            deferred.push(definition);
+        }
+        else if (visibility === "disabled") {
+            disabled.push(definition);
+        }
+        else if (maxVisibleTools !== undefined && visible.length >= maxVisibleTools) {
+            deferred.push(definition);
+        }
+        else {
+            visible.push(definition);
+        }
+    }
+    for (const toolId of profile.hiddenToolIds ?? []) {
+        const definition = definitionById.get(toolId);
+        if (definition !== undefined && !runtimeOnly.some((tool) => tool.id === definition.id)) {
+            runtimeOnly.push({ ...definition, visibility: "runtime" });
+        }
+    }
+    return {
+        profile: profile.name,
+        modelVisible: visible,
+        deferred,
+        runtimeOnly,
+        disabled,
+    };
+}
+function resolveVisibility(definition, deferredIds, hiddenIds) {
+    if (hiddenIds.has(definition.id)) {
+        return "runtime";
+    }
+    if (deferredIds.has(definition.id)) {
+        return "deferred";
+    }
+    return definition.visibility;
+}
+function missingToolDefinition(toolId) {
+    return {
+        id: toolId,
+        title: `Missing ${toolId}`,
+        layer: "runtime",
+        visibility: "disabled",
+        risk: "safe",
+        interaction: "govern",
+        description: "Tool id is referenced by a profile but no semantic definition is registered.",
+        inputSchema: { type: "object", additionalProperties: false, properties: {} },
+    };
+}
+function emptyToolSet(profile) {
+    return {
+        profile,
+        modelVisible: [],
+        deferred: [],
+        runtimeOnly: [],
+        disabled: [],
+    };
+}
+export const defaultToolBaseRegistry = createToolBaseRegistry();

package/dist/toolBase/runtimePorts.d.ts

@@ -0,0 +1,21 @@
+import type { ToolBaseInvocation, ToolBaseResult } from "./types.js";
+export type ToolBaseRuntimeContext = {
+    runtimeId: string;
+    sessionId?: string;
+    workspaceRoot?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type ToolBaseRuntimePortName = "shell" | "filesystem" | "search" | "patch" | "web" | "plan" | "userInteraction" | "skill" | "mcp" | "agent" | "context" | "approval" | "sandbox" | "pathPolicy" | "networkPolicy" | "output" | (string & {});
+export type ToolBaseRuntimeHandler = (invocation: ToolBaseInvocation, context: ToolBaseRuntimeContext) => Promise<ToolBaseResult> | ToolBaseResult;
+export type ToolBaseRuntimePort = {
+    name: ToolBaseRuntimePortName;
+    ready: boolean;
+    handler?: ToolBaseRuntimeHandler;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type ToolBaseRuntimePortRegistry = {
+    listPorts(): readonly ToolBaseRuntimePort[];
+    getPort(name: ToolBaseRuntimePortName): ToolBaseRuntimePort | undefined;
+    hasReadyPorts(names: readonly ToolBaseRuntimePortName[]): boolean;
+};
+export declare function createToolBaseRuntimePortRegistry(ports: readonly ToolBaseRuntimePort[]): ToolBaseRuntimePortRegistry;

package/dist/toolBase/runtimePorts.js

@@ -0,0 +1,8 @@
+export function createToolBaseRuntimePortRegistry(ports) {
+    const portByName = new Map(ports.map((port) => [port.name, port]));
+    return {
+        listPorts: () => ports,
+        getPort: (name) => portByName.get(name),
+        hasReadyPorts: (names) => names.every((name) => portByName.get(name)?.ready === true),
+    };
+}

package/dist/toolBase/types.d.ts

@@ -0,0 +1,74 @@
+export type ToolBaseLayer = "core" | "agent" | "optional" | "runtime";
+export type ToolBaseVisibility = "model" | "deferred" | "runtime" | "disabled";
+export type ToolBaseRisk = "safe" | "read" | "write" | "network" | "execute" | "dangerous";
+export type ToolBaseInteraction = "inspect" | "mutate" | "execute" | "delegate" | "ask" | "govern" | "generate";
+export type ToolBaseSchema = Readonly<Record<string, unknown>>;
+export type ToolBaseId = "shell.run" | "file.read" | "file.write" | "file.edit" | "file.search" | "patch.apply" | "web.search" | "web.fetch" | "plan.update" | "user.ask" | "agent.spawn" | "agent.message" | "agent.wait" | "skill.load" | "context.load" | "mcp.use" | "mcp.resources" | "lsp.query" | "browser.use" | "computer.use" | "image.view" | "image.generate" | "audio.transcribe" | "media.generate" | "memory.use" | "repo.inspect" | "approval.request" | "permission.check" | "sandbox.run" | "artifact.store" | "output.truncate" | "process.wait" | "process.kill" | "secret.resolve" | "tool.discover" | "tool.describe" | (string & {});
+export type ToolBaseDefinition = {
+    id: ToolBaseId;
+    title: string;
+    layer: ToolBaseLayer;
+    visibility: ToolBaseVisibility;
+    risk: ToolBaseRisk;
+    interaction: ToolBaseInteraction;
+    description: string;
+    inputSchema: ToolBaseSchema;
+    outputSchema?: ToolBaseSchema;
+    aliases?: readonly string[];
+    capabilityTags?: readonly string[];
+    requiresRuntimePorts?: readonly string[];
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type ToolBaseProfileName = "minimalCoding" | "standardAgent" | "extendedAgent" | "runtimeOnly" | (string & {});
+export type ToolBaseProfile = {
+    name: ToolBaseProfileName;
+    description: string;
+    defaultVisibility: ToolBaseVisibility;
+    toolIds: readonly ToolBaseId[];
+    hiddenToolIds?: readonly ToolBaseId[];
+    deferredToolIds?: readonly ToolBaseId[];
+};
+export type ToolBaseProviderShape = "openai.responses" | "openai.chat_completions" | "anthropic.messages" | "google.generate_content" | "bedrock.converse" | "openai.compatible_chat" | "custom";
+export type ToolBaseProviderCapability = {
+    shape: ToolBaseProviderShape;
+    supportsParallelToolCalls?: boolean;
+    supportsStrictJsonSchema?: boolean;
+    supportsFreeformToolInput?: boolean;
+    maxVisibleTools?: number;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type ToolBaseToolSet = {
+    profile: ToolBaseProfileName;
+    modelVisible: readonly ToolBaseDefinition[];
+    deferred: readonly ToolBaseDefinition[];
+    runtimeOnly: readonly ToolBaseDefinition[];
+    disabled: readonly ToolBaseDefinition[];
+};
+export type ToolBaseInvocation = {
+    invocationId: string;
+    toolId: ToolBaseId;
+    input: unknown;
+    modelTurnId?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type ToolBaseResult = {
+    ok: true;
+    invocationId: string;
+    toolId: ToolBaseId;
+    output: unknown;
+    publicSummary?: string;
+    metadata?: Readonly<Record<string, unknown>>;
+} | {
+    ok: false;
+    invocationId: string;
+    toolId: ToolBaseId;
+    error: ToolBasePublicError;
+    metadata?: Readonly<Record<string, unknown>>;
+};
+export type ToolBasePublicError = {
+    code: string;
+    message: string;
+    retryable: boolean;
+    safeForModel: true;
+    internalDetailExposed: false;
+};

package/dist/toolBase/types.js

@@ -0,0 +1,6 @@
+/*
+ * 文件定位：Praxis 新工具层的语义合同。
+ * 核心目的：定义模型可见工具、运行时隐藏能力、调用结果和工具 profile 的稳定内部格式。
+ * 边界：这里不写 provider wire schema，也不执行真实 shell / 文件 / 网络副作用。
+ */
+export {};

package/examples/README.md

@@ -0,0 +1,18 @@
+# Praxis Example
+
+`minimal/` 是最小 Agent 写法，适合看核心链路。
+
+`fullstack/` 是完整 AI 应用工程写法，适合看工程极限：
+
+- project-level `application/authentication/context/memory/topology/tests`
+- agent-level `agents/repoInspector/config/prompts/tools/policies/mainLoop/harness/sandbox/storage/state/interfaces`
+
+运行：
+
+```bash
+node --import tsx examples/minimal/runRepoInspector.ts
+bin/rax inspect examples/fullstack
+bin/rax test examples/fullstack
+bin/rax run examples/fullstack "Inspect this Praxis fullstack agent project."
+node --import tsx examples/fullstack/application/runRepoInspector.ts --deep --shell --skill-authoring --policy=permissive
+```

package/examples/fullstack/README.md

@@ -0,0 +1,65 @@
+# Praxis Fullstack Example
+
+`fullstack` 在这里被当成一个完整 AI 应用工程项目，而不是单个 Agent 文件夹。
+
+项目级入口：
+
+- `rax.project.json`：工程描述，`rax inspect/test/run examples/fullstack` 会从这里找到 Agent 入口。
+- `application/`：真实应用层，负责把 Agent 接成产品行为、CLI/TUI/Raxode/Raxos 入口。
+- `agents/`：一个项目可以有多个 Agent；当前主 Agent 是 `agents/repoInspector/`。
+- `authentication/`：开发期和运行期 auth/profile 引用策略，不保存 raw secret。
+- `context/`：CMP bridge/contract 占位。
+- `memory/`：MP bridge/contract 占位。
+- `topology/`：multiagent 拓扑 bridge/contract 占位。
+- `tests/`：项目级测试。
+
+主 Agent 子工程：
+
+```text
+agents/repoInspector/
+  praxis.agent.ts
+  agent.ts
+  config/
+  prompts/
+  tools/
+  policies/
+  mainLoop/
+  harness/
+  sandbox/
+  storage/
+  state/
+  interfaces/
+```
+
+这里的分工是：
+
+- `tools/` 只说“这个 Agent 挂哪些工具”。
+- `policies/` 只说“这些行为怎么治理”。
+- `mainLoop/` 只说“动作、hook、trigger、继续/中断策略引用”。
+- `prompts/` 不只是放文本；运行时会把 prompt 包分成 `stableSystemCore / declaredRuntimeContext / toolDeclarations / projectContext / sessionSummary / memoryContext / retrievedContext / observations / userTurn / assistantScratchpadPlan`，用于缓存健康检查。
+- `harness/` 很薄，只负责总装配：用 refs 把 model、promptPack、tools、toolPolicy、mainLoop、sandbox、storage、session、statePlane、interfaces、context、memory 串成声明式能力外壳。
+- `application/` 才是最终产品/应用入口，不放进单个 Agent 内部。
+
+推荐 rax 入口：
+
+```bash
+bin/rax inspect examples/fullstack
+bin/rax test examples/fullstack
+bin/rax run examples/fullstack "Inspect this Praxis fullstack agent project."
+```
+
+本地调试入口：
+
+```bash
+node --import tsx examples/fullstack/runRepoInspector.ts
+node --import tsx examples/fullstack/application/runRepoInspector.ts --deep --shell --skill-authoring --policy=permissive
+node --no-warnings --import tsx examples/fullstack/application/runRepoInspector.ts --sqlite
+```
+
+默认 dry-run，不需要真实模型 auth。
+
+`application/runRepoInspector.ts` 会额外打印：
+
+- `PromptPack Turn Preview`：本轮 PromptPack 分段和 cache plan。
+- `Framework Inspection.promptCache`：`rax inspect` 以后应该呈现给开发者的缓存健康信息。
+- `Runtime Result.cachePlanSteps`：Kernel 运行时实际持久化的 `buildCachePlan` mainLoop step。

package/examples/fullstack/agents/repoInspector/README.md

@@ -0,0 +1,13 @@
+# RepoInspector Agent
+
+这是 `examples/fullstack` 项目里的一个 Agent 子工程。
+
+- `praxis.agent.ts` 是 rax 可编译入口。
+- `agent.ts` 是 OAO Agent class。
+- `config/` 管 identity/model/modelFleet/options。
+- `prompts/` 管 PromptPack class 和 prompt package。
+- `tools/` 管工具集合，不写治理结论。
+- `policies/` 管治理矩阵，不声明工具清单。
+- `mainLoop/` 管主循环扩展点 refs。
+- `harness/` 只做能力外壳装配；它用 refs 把 model、promptPack、tools、toolPolicy、mainLoop、sandbox、storage、session、statePlane、interfaces、context、memory 串成一个可编译外壳。
+- `sandbox/ storage/ state/ interfaces/` 分别接运行边界、持久化、状态面、外部承接面。

package/examples/fullstack/agents/repoInspector/agent.ts

@@ -0,0 +1,71 @@
+import { praxis } from "@praxis-ai/praxis";
+import type {
+  AgentIdentity,
+  BaseToolPolicyMatrixSpec,
+  HarnessSpec,
+  MainLoopSpec,
+  ModelFleetSpec,
+  ModelSpec,
+  SandboxSpec,
+  SessionSpec,
+  StatePlaneSpec,
+  StorageSpec,
+} from "@praxis-ai/praxis";
+
+import { createRepoInspectorIdentity } from "./config/identity.js";
+import { createRepoInspectorModel, createRepoInspectorModelFleet } from "./config/modelPlane.js";
+import {
+  normalizeRepoInspectorOptions,
+  type RepoInspectorOptions,
+} from "./config/repoInspectorOptions.js";
+import { createRepoInspectorHarness } from "./harness/repoInspectorHarness.js";
+import { createRepoInspectorMainLoop } from "./mainLoop/repoInspectorMainLoop.js";
+import { createRepoInspectorToolPolicy } from "./policies/toolPolicy.js";
+import { RepoInspectorPrompt } from "./prompts/repoInspectorPrompt.js";
+import { createRepoInspectorSandbox } from "./sandbox/profile.js";
+import { createRepoInspectorStatePlane } from "./state/statePlane.js";
+import { createRepoInspectorSession, createRepoInspectorStorage } from "./storage/storagePolicy.js";
+
+export class RepoInspectorAgent extends praxis.AgentArchetype {
+  identity: AgentIdentity;
+  model: ModelSpec;
+  modelFleet: ModelFleetSpec;
+  promptPack: RepoInspectorPrompt;
+  mainLoop: MainLoopSpec;
+  storage: StorageSpec;
+  sandbox: SandboxSpec;
+  toolPolicy: BaseToolPolicyMatrixSpec;
+  session: SessionSpec;
+  statePlane: StatePlaneSpec;
+  harness: HarnessSpec;
+
+  constructor(options: RepoInspectorOptions = {}) {
+    super();
+    const normalized = normalizeRepoInspectorOptions(options);
+
+    this.identity = createRepoInspectorIdentity(normalized);
+    this.model = createRepoInspectorModel(normalized);
+    this.modelFleet = createRepoInspectorModelFleet(normalized);
+    this.promptPack = new RepoInspectorPrompt();
+    this.mainLoop = createRepoInspectorMainLoop(normalized);
+    this.sandbox = createRepoInspectorSandbox(normalized);
+    this.toolPolicy = createRepoInspectorToolPolicy(normalized.policyProfile);
+    this.storage = createRepoInspectorStorage(normalized);
+    this.session = createRepoInspectorSession(normalized);
+    this.statePlane = createRepoInspectorStatePlane();
+    this.harness = createRepoInspectorHarness(normalized);
+  }
+}
+
+export class DeepPermissiveRepoInspectorAgent extends RepoInspectorAgent {
+  constructor(options: Pick<RepoInspectorOptions, "persistence" | "sandboxProfile"> = {}) {
+    super({
+      mode: "deep",
+      policyProfile: "permissive",
+      includeShell: true,
+      includeSkillAuthoring: true,
+      persistence: options.persistence,
+      sandboxProfile: options.sandboxProfile,
+    });
+  }
+}

package/examples/fullstack/agents/repoInspector/config/identity.ts

@@ -0,0 +1,12 @@
+import type { AgentIdentity } from "@praxis-ai/praxis";
+
+import type { NormalizedRepoInspectorOptions } from "./repoInspectorOptions.js";
+
+export function createRepoInspectorIdentity(options: NormalizedRepoInspectorOptions): AgentIdentity {
+  return {
+    id: `agent.example.repoInspector.${options.mode}.${options.policyProfile}`,
+    name: "Repo Inspector Agent",
+    version: "0.1.0",
+    description: "一个用于真实测试 Praxis framework authoring 面的仓库观察 Agent。",
+  };
+}

package/examples/fullstack/agents/repoInspector/config/modelPlane.ts

@@ -0,0 +1,68 @@
+import { praxis } from "@praxis-ai/praxis";
+import type { ModelFleetSpec, ModelSpec } from "@praxis-ai/praxis";
+
+import type { NormalizedRepoInspectorOptions } from "./repoInspectorOptions.js";
+
+export function createRepoInspectorModel(options: NormalizedRepoInspectorOptions): ModelSpec {
+  return praxis.model("gpt-5.5", {
+    provider: "openai",
+    endpointShape: "responses",
+    carrierId: `carrier.example.repoInspector.${options.mode}.${options.policyProfile}`,
+    reasoning: {
+      effort: options.mode === "deep" ? "high" : "low",
+      summary: "concise",
+    },
+  });
+}
+
+export function createRepoInspectorModelFleet(options: NormalizedRepoInspectorOptions): ModelFleetSpec {
+  return praxis.modelFleet.auto({
+    primary: praxis.endpoint("/v1/responses", {
+      role: "background",
+      provider: "openai",
+      model: "gpt-5.5",
+      carrierId: `carrier.example.repoInspector.${options.mode}.${options.policyProfile}`,
+      capabilityMatrix: { text: true, toolCalling: true },
+      failurePolicy: { onUnavailable: "degrade", maxRetries: 1, timeoutMs: 20_000 },
+    }),
+    reasoning: praxis.endpoint("/v1/messages", {
+      role: "reasoning",
+      provider: "anthropic-compatible",
+      model: "claude-opus-style",
+      capabilityMatrix: { text: true, reasoning: true, metadata: { longContext: true } },
+      failurePolicy: { onUnavailable: "degrade", maxRetries: 1 },
+    }),
+    image: praxis.endpoint("/v1/images", {
+      role: "image-generation",
+      provider: "openai",
+      model: "gpt-image-style",
+      capabilityMatrix: { imageGeneration: true },
+      failurePolicy: { onUnavailable: "skip" },
+    }),
+    batch: praxis.endpoint("/v1/batches", {
+      role: "batch",
+      provider: "openai",
+      model: "gpt-batch-style",
+      capabilityMatrix: { batch: true },
+      failurePolicy: { onUnavailable: "skip", maxRetries: 1 },
+    }),
+    realtime: praxis.endpoint("/v1/realtime", {
+      role: "realtime",
+      provider: "openai",
+      model: "gpt-realtime-style",
+      capabilityMatrix: { realtime: true },
+      failurePolicy: { onUnavailable: "degrade" },
+    }),
+  }, {
+    probeStrategy: "lazy",
+    primaryRef: "primary",
+    failurePolicy: {
+      onUnavailable: "degrade",
+      fallbackEndpointRef: "primary",
+      maxRetries: 1,
+      metadata: {
+        optionalEndpointPolicy: "record-and-continue",
+      },
+    },
+  });
+}

package/examples/fullstack/agents/repoInspector/config/repoInspectorOptions.ts

@@ -0,0 +1,29 @@
+export type RepoInspectorMode = "quick" | "deep";
+
+export type RepoInspectorPolicyProfile = "standard" | "restricted" | "permissive" | "yolo" | "bapr";
+
+export type RepoInspectorSandboxProfile = "hostObserved" | "workspaceOnly" | "linuxBubblewrap";
+
+export type RepoInspectorOptions = {
+  mode?: RepoInspectorMode;
+  policyProfile?: RepoInspectorPolicyProfile;
+  sandboxProfile?: RepoInspectorSandboxProfile;
+  includeShell?: boolean;
+  includeSkillAuthoring?: boolean;
+  includeAllTestable?: boolean;
+  persistence?: "memory" | "sqlite";
+};
+
+export type NormalizedRepoInspectorOptions = Required<RepoInspectorOptions>;
+
+export function normalizeRepoInspectorOptions(options: RepoInspectorOptions = {}): NormalizedRepoInspectorOptions {
+  return {
+    mode: options.mode ?? "quick",
+    policyProfile: options.policyProfile ?? "standard",
+    sandboxProfile: options.sandboxProfile ?? "hostObserved",
+    includeShell: options.includeShell === true || options.includeAllTestable === true,
+    includeSkillAuthoring: options.includeSkillAuthoring === true || options.includeAllTestable === true,
+    includeAllTestable: options.includeAllTestable ?? false,
+    persistence: options.persistence ?? "sqlite",
+  };
+}