@hcflabs/pi-subagent 0.0.0-stage → 27.10.8

package/dist/index.d.ts

@@ -0,0 +1,170 @@
+import { type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { resolveTaskModelRoute, type AvailableModel, type ModelTask, type ProfileName, type ResolvedTaskRoute, type ThinkingLevel } from "@hcflabs/pi-task-models";
+export { DISPLAY_TEXT_CONTRACT, hasDisplayControlCharacters } from "./display-text.ts";
+export { loadRoleMcpConfig, parseRoleMcpAllowlist } from "./mcp-role.ts";
+export { addUsage, capEphemeralSubagentOutput, createEphemeralSubagentExecutor, DEFAULT_MAX_TURNS, EphemeralSubagentError, EXECUTION_BUDGET_ENV, formatDuration, type EphemeralSubagentActivityEvent, type EphemeralSubagentErrorCode, type EphemeralSubagentExecutionBudget, type EphemeralSubagentExecutor, type EphemeralSubagentExecutorOptions, type EphemeralSubagentResult, type EphemeralSubagentRunInput, type EphemeralSubagentTimeout, } from "./ephemeral.ts";
+export { createChildWorktree, finalizeChildWorktree, inspectIndexFlags, inspectWorktreeDirty, WorktreeSetupError, type WorktreeDirtyInspection, type WorktreeInfo, type WorktreePayload, } from "./worktree.ts";
+export { prepareExactReviewEvidence, REVIEW_MAX_PATCH_BYTES, REVIEW_MAX_PATHS, type PreparedReviewEvidence, type PrepareExactReviewEvidenceInput, } from "./review-evidence.ts";
+export { PI_SUBAGENT_PROCESS_LEASE } from "./process-lease.ts";
+export declare const ROLE_MCP_POLICY_FLAG = "pi-subagent-role-mcps";
+export declare const ROLE_TOOL_POLICY_FLAG = "pi-subagent-role-tools";
+/** Read child MCP policy before Pi binds registered extension flag values. */
+export declare function roleMcpAllowlistFromArgv(args: readonly string[]): string[];
+/** Parse the Role tool policy flag value: JSON tool names. */
+export declare function parseRoleToolPolicy(value: unknown): string[];
+/** Read child tool policy before Pi binds registered extension flag values. */
+export declare function roleToolPolicyFromArgv(args: readonly string[]): string[];
+/**
+ * Whether a tool policy activates `codemode` in the child, so scripts can reach tools with
+ * `codemode` or `deferred` exposure. Loading `builtin:codemode` alone registers the tool inactive.
+ */
+export declare function roleActivatesCodemode(tools: readonly string[]): boolean;
+export declare const CHILD_EXCLUDED_TOOL_NAMES: readonly ["delegate_task", "ask_question", "subagent_status", "subagent_resume", "subagent_stage", "subagent_integrate", "subagent_abort", "herdr_handoff"];
+export declare const DELEGATE_TASK: {
+    readonly id: "pi-subagent/delegateTask";
+    readonly label: "Subagent delegation";
+    readonly purpose: "Launch direct or checked isolated Pi delegation.";
+    readonly defaultProfile: "fast";
+};
+export type RoleName = string;
+export interface Role {
+    name: RoleName;
+    description: string;
+    modelClass?: ProfileName;
+    tools: string[];
+    extensions: string[];
+    skills: string[];
+    mcps?: string[];
+    systemPrompt: string;
+}
+/** Optional `config.json` resources merged into every Role, defaults first. */
+export interface RoleDefaults {
+    extensions?: string[];
+    tools?: string[];
+    skills?: string[];
+}
+export type RoleSource = "built-in" | "user override" | "user";
+/** One invalid user Role file. `name` is the claimed Role name, or the file stem when unreadable. */
+export interface RoleFileError {
+    file: string;
+    name: RoleName;
+    message: string;
+}
+export interface RoleCatalog {
+    roles: Role[];
+    sources: ReadonlyMap<RoleName, RoleSource>;
+    errors: RoleFileError[];
+}
+export interface PiLaunch {
+    env: Record<string, string>;
+    args: string[];
+}
+export interface ResolvedRoleLaunch extends PiLaunch {
+    model: AvailableModel;
+    thinkingLevel: ThinkingLevel;
+    missingSkills: string[];
+}
+export interface PreparedRoleLaunch extends ResolvedRoleLaunch {
+    role: RoleName;
+    tools: readonly string[];
+    systemPrompt: string;
+    promptArgIndex: number;
+}
+export interface CreateRoleLaunchInput {
+    role: Role;
+    route: ResolvedTaskRoute;
+    extensions?: readonly string[];
+    tools?: readonly string[];
+    env?: Readonly<Record<string, string>>;
+}
+export interface ResolveRoleLaunchInput extends Omit<CreateRoleLaunchInput, "route"> {
+    task: ModelTask;
+    modelClass?: ProfileName;
+    agentDir?: string;
+}
+export interface ResolveConfiguredRoleLaunchInput {
+    role: string;
+    modelClass: ProfileName;
+}
+export interface ResolvedRoleSkills {
+    paths: string[];
+    missing: string[];
+}
+/** Normalize one arbitrary Role name using the Role configuration contract. */
+export declare function parseRoleName(value: unknown, source?: string): RoleName;
+/** Validate `config.json` `roleDefaults` with the same rules as Role fields; `label` prefixes errors. */
+export declare function parseRoleDefaults(value: unknown, label?: string): RoleDefaults;
+export interface SubagentConfig {
+    maxSubagents: number;
+    maxTurns: number;
+    maxTokens: number | undefined;
+    maxCorrections: number;
+    timeout: {
+        idleMinutes: number;
+        maxMinutes: number;
+    };
+    roleDefaults: RoleDefaults;
+}
+export declare const DEFAULT_SUBAGENT_CONFIG: Readonly<SubagentConfig>;
+/**
+ * The user `config.json` store shared by the extension and `loadRoleCatalog`.
+ * Invalid bounded limits and `roleDefaults` keys fall back to defaults; an
+ * invalid `maxTokens` disables the config because its default is unlimited.
+ */
+export declare function createSubagentConfigStore(agentDir?: string): import("@hcflabs/pi-config-store").ConfigStore<import("@hcflabs/pi-config-store").FieldsValue<{
+    maxSubagents: import("@hcflabs/pi-config-store").Field<number>;
+    maxTurns: import("@hcflabs/pi-config-store").Field<number>;
+    maxTokens: import("@hcflabs/pi-config-store").Field<number | undefined>;
+    maxCorrections: import("@hcflabs/pi-config-store").Field<number>;
+    timeout: import("@hcflabs/pi-config-store").Field<{
+        idleMinutes: number;
+        maxMinutes: number;
+    }>;
+    roleDefaults: import("@hcflabs/pi-config-store").Field<RoleDefaults>;
+}>>;
+/**
+ * Report `roleDefaults` issues at each session start, and return a function that reports them after a lazy
+ * Role catalog load, such as `loadRoleCatalog` or `resolveRoleLaunch`. Every pi-config-store reporter shares
+ * one record, so each issue shows one time in each session, also with the pi-subagent extension active.
+ */
+export declare function registerRoleDefaultsReporting(pi: Pick<ExtensionAPI, "on">, agentDir?: string): (ctx: Pick<ExtensionContext, "hasUI" | "ui">) => void;
+declare const BUILTIN_ROLE_NAMES: readonly ["implementer", "reviewer", "scout"];
+export type BuiltinRoleName = (typeof BUILTIN_ROLE_NAMES)[number];
+export declare function loadBuiltinRole(name: BuiltinRoleName): Role;
+/**
+ * Package-shipped Roles plus user Roles from `config/pi-subagent`, with
+ * `roleDefaults` merged in. A user Role overrides a same-named built-in. Each
+ * invalid or duplicate user file is reported and makes its claimed name
+ * unavailable without hiding valid Roles. Invalid `roleDefaults` keys are
+ * dropped; a `config.json` that cannot load (for example, malformed JSON) throws.
+ */
+export declare function loadRoleCatalog(agentDir?: string): RoleCatalog;
+/** Select one catalog Role, naming invalid files that claim it. */
+export declare function findRole(catalog: RoleCatalog, name: RoleName): Role;
+type TaskRouteContext = Parameters<typeof resolveTaskModelRoute>[0];
+type RoleLaunchContext = TaskRouteContext & Pick<ExtensionContext, "isProjectTrusted">;
+export declare function resolveTaskRoute(ctx: TaskRouteContext, profileName: ProfileName, agentDir?: string): ResolvedTaskRoute;
+export declare function resolveRoleSkills(pi: Pick<ExtensionAPI, "getCommands">, role: Role): ResolvedRoleSkills;
+/** Resolve all enabled package resources selected by one Role's extension sources. */
+export declare function resolveRolePackageResources(role: Role, ctx: Pick<ExtensionContext, "cwd" | "isProjectTrusted">): Promise<{
+    extensions: string[];
+    skills: string[];
+    prompts: string[];
+    themes: string[];
+}>;
+export declare function createRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: Pick<ExtensionContext, "isProjectTrusted">, input: CreateRoleLaunchInput): ResolvedRoleLaunch;
+export declare function resolveRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: RoleLaunchContext, input: ResolveRoleLaunchInput): ResolvedRoleLaunch;
+/** Prepare a resolved or resolvable Role launch while keeping its system prompt out of argv. */
+export declare function prepareRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: RoleLaunchContext, input: ResolveRoleLaunchInput): PreparedRoleLaunch;
+export declare function prepareRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: RoleLaunchContext, input: CreateRoleLaunchInput): PreparedRoleLaunch;
+/** Resolve and prepare a configured Role with its package-owned resources. */
+export declare function resolveConfiguredRoleLaunch(pi: Pick<ExtensionAPI, "getCommands">, ctx: RoleLaunchContext & Pick<ExtensionContext, "cwd">, input: ResolveConfiguredRoleLaunchInput): Promise<PreparedRoleLaunch>;
+/** Insert the system prompt pair after a caller has prepared its launch argv. */
+export declare function finalizeRoleLaunch(prepared: PreparedRoleLaunch): ResolvedRoleLaunch;
+export * from "./composition.ts";
+export * from "./git-runtime.ts";
+export * from "./herdr-runtime.ts";
+export { ISOLATED_MODEL_TASK, RoleLaunchRuntime, type LaunchRuntimeOptions } from "./launch-runtime.ts";
+export * from "./runner.ts";
+export * from "./schema.ts";
+export * from "./store.ts";