@tiangong-ai/cli 0.0.23 → 0.0.25

package/dist/research/workspace/setup.d.ts

@@ -0,0 +1,468 @@
+import { EXTERNAL_SKILL_CONTEXT_PROFILE, EXTERNAL_SKILL_MEDIA_PROFILE, EXTERNAL_SKILL_PROFILE } from "./external-skills.js";
+import { RESEARCH_SETUP_INSTALLER, type ResearchSetupAgent, type ResearchSetupCredential, type ResearchSetupScope, type ResearchSetupSkill } from "./setup-catalog.js";
+import type { AgentPricing, ResearchMode } from "./types.js";
+export type ResearchSetupEvidenceProfile = "none" | typeof EXTERNAL_SKILL_PROFILE | typeof EXTERNAL_SKILL_CONTEXT_PROFILE | typeof EXTERNAL_SKILL_MEDIA_PROFILE;
+export interface ResearchSetupAgentRoutePlan {
+    producerModel: string | null;
+    reviewerModel: string | null;
+    producerPricing: AgentPricing | null;
+    reviewerPricing: AgentPricing | null;
+}
+export interface ResearchSetupPlan {
+    schemaVersion: 1;
+    kind: "tiangong-research-setup-plan";
+    planId: string;
+    createdAt: string;
+    cli: {
+        package: "@tiangong-ai/cli";
+        version: string;
+    };
+    workspace: {
+        path: string;
+        name: string;
+        mode: ResearchMode;
+    };
+    install: {
+        scope: ResearchSetupScope;
+        agents: ResearchSetupAgent[];
+        mode: "copy";
+        installer: typeof RESEARCH_SETUP_INSTALLER;
+        targets: Array<{
+            agent: ResearchSetupAgent;
+            root: string;
+        }>;
+    };
+    selection: {
+        evidenceProfile: ResearchSetupEvidenceProfile;
+        skillIds: string[];
+    };
+    sources: Array<{
+        id: string;
+        repository: string;
+        locator: string;
+        immutableRef: string;
+    }>;
+    skills: Array<{
+        id: string;
+        skillName: string;
+        sourceId: string;
+        sourceRelativePath: string;
+        expectedTreeSha256: string;
+        role: ResearchSetupSkill["role"];
+        licenseId: string;
+    }>;
+    acceptedLicenses: Array<{
+        skillId: string;
+        licenseId: string;
+        accepted: true;
+    }>;
+    credentialSources: Array<{
+        id: string;
+        fromEnvironment: string;
+        storage: ResearchSetupCredential["storage"];
+    }>;
+    settings: Record<string, string>;
+    agentRoutes: ResearchSetupAgentRoutePlan;
+    checks: {
+        live: boolean;
+        allowSyntheticUnstructureUpload: boolean;
+        agentSmoke: boolean;
+    };
+    confirmations: {
+        networkDownloads: true;
+        globalMutation: boolean;
+        agentSmokeCost: boolean;
+    };
+    mutations: Array<{
+        step: string;
+        target: string;
+        reason: string;
+    }>;
+    planSha256: string;
+}
+export interface ResearchSetupState {
+    schemaVersion: 1;
+    planSha256: string;
+    status: "pending" | "applying" | "partially-ready" | "ready" | "blocked";
+    currentStep: string | null;
+    completedSteps: string[];
+    attempts: number;
+    updatedAt: string;
+    lastError: {
+        code: string;
+        step: string;
+        reason: string;
+        minimumAction: string;
+        retryCommand: string;
+    } | null;
+}
+export interface ResearchSetupPlanInput {
+    workspace: string;
+    name?: string;
+    mode: ResearchMode;
+    evidenceProfile: ResearchSetupEvidenceProfile;
+    skillIds: string[];
+    scope?: ResearchSetupScope;
+    agents?: ResearchSetupAgent[];
+    acceptedLicenseIds: string[];
+    credentialEnvironment?: Record<string, string>;
+    settings?: Record<string, string>;
+    agentRoutes?: Partial<ResearchSetupAgentRoutePlan>;
+    liveChecks?: boolean;
+    allowSyntheticUnstructureUpload?: boolean;
+    agentSmoke?: boolean;
+    confirmNetworkDownloads: boolean;
+    confirmGlobalMutation?: boolean;
+    confirmAgentSmokeCost?: boolean;
+    replacePlan?: boolean;
+    environment?: NodeJS.ProcessEnv;
+    targetRoots?: Partial<Record<ResearchSetupAgent, string>>;
+}
+export interface SetupCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}
+export type SetupCommandRunner = (input: {
+    command: string;
+    args: string[];
+    cwd: string;
+    environment: NodeJS.ProcessEnv;
+    timeoutMs: number;
+}) => Promise<SetupCommandResult>;
+export interface ApplyResearchSetupOptions {
+    environment?: NodeJS.ProcessEnv;
+    runner?: SetupCommandRunner;
+    fetcher?: typeof fetch;
+    sleeper?: (milliseconds: number) => Promise<unknown>;
+    skipDoctor?: boolean;
+}
+export type ResearchSetupCompanionInput = {
+    workspace: string;
+    skillId: "tiangong.document-granular-decompose";
+    inputPath: string;
+    outputPath: string;
+    timeoutSeconds?: number;
+} | {
+    workspace: string;
+    skillId: "tiangong.academic-paper-download";
+    outputDirectory: string;
+    doi?: string;
+    title?: string;
+    author?: string;
+    year?: number;
+    timeoutSeconds?: number;
+};
+export interface RunResearchSetupCompanionOptions {
+    environment?: NodeJS.ProcessEnv;
+    runner?: SetupCommandRunner;
+}
+export declare function createResearchSetupPlan(input: ResearchSetupPlanInput): Promise<ResearchSetupPlan>;
+export declare function loadAndVerifyResearchSetupPlan(planPath: string): Promise<ResearchSetupPlan>;
+export declare function createResearchSetupUpgradePlan(input: {
+    workspace: string;
+    acceptedLicenseIds: string[];
+    confirmUpgrade: boolean;
+    environment?: NodeJS.ProcessEnv;
+}): Promise<ResearchSetupPlan>;
+export declare function applyResearchSetupPlan(planPath: string, options?: ApplyResearchSetupOptions): Promise<{
+    schemaVersion: 1;
+    plan: ResearchSetupPlan;
+    state: ResearchSetupState;
+    report: null;
+} | {
+    schemaVersion: 1;
+    plan: ResearchSetupPlan;
+    state: ResearchSetupState;
+    report: Record<string, unknown> & {
+        readiness: "READY" | "PARTIALLY_READY" | "BLOCKED";
+    };
+}>;
+export declare function inspectResearchSetupStatus(workspace: string, environment?: NodeJS.ProcessEnv): Promise<{
+    schemaVersion: 1;
+    workspace: string;
+    plan: {
+        planId: string;
+        planSha256: string;
+        cliVersion: string;
+        mode: ResearchMode;
+        scope: ResearchSetupScope;
+        agents: ResearchSetupAgent[];
+        selectedSkillIds: string[];
+    };
+    state: ResearchSetupState;
+    installations: {
+        skillId: string;
+        skillName: string;
+        agent: ResearchSetupAgent;
+        path: string;
+        status: "missing" | "installed" | "drifted" | "blocked";
+        observedTreeSha256: string | null;
+        detail: string;
+    }[];
+    report: unknown;
+    next: {
+        code: string;
+        step: string;
+        reason: string;
+        minimumAction: string;
+        retryCommand: string;
+    } | {
+        minimumAction: string;
+        retryCommand: string;
+    } | null;
+}>;
+export declare function setResearchSetupCredentialFromEnvironment(input: {
+    workspace: string;
+    credentialId: string;
+    environmentName: string;
+    environment: NodeJS.ProcessEnv;
+}): Promise<{
+    schemaVersion: 1;
+    workspace: string;
+    credentialId: string;
+    configured: true;
+    storage: "broker" | "adapter";
+    outputPolicy: "value-is-never-emitted";
+}>;
+export declare function runResearchSetupCompanion(input: Extract<ResearchSetupCompanionInput, {
+    skillId: "tiangong.document-granular-decompose";
+}>, options?: RunResearchSetupCompanionOptions): ReturnType<typeof runDocumentGranularCompanion>;
+export declare function runResearchSetupCompanion(input: Extract<ResearchSetupCompanionInput, {
+    skillId: "tiangong.academic-paper-download";
+}>, options?: RunResearchSetupCompanionOptions): ReturnType<typeof runAcademicPaperCompanion>;
+export declare function doctorResearchSetup(workspace: string, options?: {
+    live?: boolean;
+    allowSyntheticUnstructureUpload?: boolean;
+    agentSmoke?: boolean;
+    environment?: NodeJS.ProcessEnv;
+    runner?: SetupCommandRunner;
+    fetcher?: typeof fetch;
+    sleeper?: (milliseconds: number) => Promise<unknown>;
+}): Promise<Record<string, unknown> & {
+    readiness: "READY" | "PARTIALLY_READY" | "BLOCKED";
+}>;
+export declare function retryResearchSetup(input: {
+    workspace: string;
+    step: string;
+    clearStaleLock?: boolean;
+    options?: ApplyResearchSetupOptions;
+}): Promise<{
+    schemaVersion: 1;
+    plan: ResearchSetupPlan;
+    state: ResearchSetupState;
+    report: null;
+} | {
+    schemaVersion: 1;
+    plan: ResearchSetupPlan;
+    state: ResearchSetupState;
+    report: Record<string, unknown> & {
+        readiness: "READY" | "PARTIALLY_READY" | "BLOCKED";
+    };
+}>;
+export declare function checkResearchSetupUpdates(workspace: string, environment?: NodeJS.ProcessEnv): Promise<{
+    schemaVersion: 1;
+    workspace: string;
+    checkedAt: string;
+    updateAvailable: boolean;
+    cliVersionDrift: {
+        planned: string;
+        active: string;
+    } | null;
+    drift: ({
+        skillId: string;
+        status: "removed";
+    } | {
+        skillId: string;
+        status: "catalog-updated";
+        plannedTreeSha256: string;
+        currentTreeSha256: string;
+    })[];
+    currentInstaller: {
+        readonly package: "skills";
+        readonly version: "1.5.22";
+        readonly npmIntegrity: "sha512-cHiLjwZEawWFvudIqeeMZlvZayTLbRouydMbblyrdiyH7ZLbqUrSrEEr+Tg+X265iztRlVMsyOYRwpD5JxBsvg==";
+        readonly npmShasum: "ec0a7897ba2ef06e01f3b41007886f3a92cf4d05";
+        readonly gitHead: "a4d243c3d4f86cdf9385dd1b6a0733f6937e70b5";
+        readonly runtimeInstall: false;
+    };
+    catalog: {
+        schemaVersion: 1;
+        catalog: string;
+        policy: {
+            bundledSkills: boolean;
+            userInitiatedOnly: boolean;
+            runtimeInstall: boolean;
+            defaultScope: string;
+            defaultInstallMode: string;
+            floatingUpdates: boolean;
+            automaticSystemPackageInstall: boolean;
+            automaticPythonPackageInstall: boolean;
+        };
+        installer: {
+            readonly package: "skills";
+            readonly version: "1.5.22";
+            readonly npmIntegrity: "sha512-cHiLjwZEawWFvudIqeeMZlvZayTLbRouydMbblyrdiyH7ZLbqUrSrEEr+Tg+X265iztRlVMsyOYRwpD5JxBsvg==";
+            readonly npmShasum: "ec0a7897ba2ef06e01f3b41007886f3a92cf4d05";
+            readonly gitHead: "a4d243c3d4f86cdf9385dd1b6a0733f6937e70b5";
+            readonly runtimeInstall: false;
+        };
+        workspace: string;
+        scope: ResearchSetupScope;
+        agents: ResearchSetupAgent[];
+        sources: readonly import("./setup-catalog.js").ResearchSetupSource[];
+        entries: {
+            source: import("./setup-catalog.js").ResearchSetupSource;
+            installations: {
+                status: "missing" | "installed" | "drifted" | "blocked";
+                observedTreeSha256: string | null;
+                detail: string;
+                agent: ResearchSetupAgent;
+                root: string;
+                path: string;
+            }[];
+            id: string;
+            skillName: string;
+            sourceId: string;
+            sourceRelativePath: string;
+            expectedTreeSha256: string;
+            tier: import("./setup-catalog.js").ResearchSetupTier;
+            role: import("./setup-catalog.js").ResearchSetupRole;
+            purpose: string;
+            recommendedFor: string[];
+            defaultSelected: boolean;
+            credentialIds: string[];
+            settingIds: string[];
+            dependencies: import("./setup-catalog.js").ResearchSetupDependency[];
+            license: import("./setup-catalog.js").ResearchSetupLicense;
+            conflictGroup: string | null;
+            capabilityKind: "brave-public-internet" | "tiangong-sci" | null;
+            bundled: false;
+            userInitiatedOnly: true;
+        }[];
+        credentials: readonly ResearchSetupCredential[];
+        settings: readonly import("./setup-catalog.js").ResearchSetupSetting[];
+        conflictGroups: never[];
+        selectionGuidance: {
+            readonly pptCreation: {
+                readonly preferredSkillId: "hugohe3.ppt-master";
+                readonly situationalSkillIds: readonly ["anthropic.pptx"];
+                readonly maySelectTogether: true;
+                readonly automaticSelection: false;
+                readonly guidance: "Prefer PPT Master for creating PPT presentations; use Anthropic PPTX when its workflow better fits the task. Both remain explicit post-closure choices.";
+            };
+        };
+        roles: {
+            evidenceCapabilities: string[];
+            inputPreprocessors: string[];
+            acquisitionAdapters: string[];
+            postClosureAuthoring: string[];
+        };
+    };
+    policy: {
+        automaticUpdate: boolean;
+        floatingUpdate: boolean;
+        minimumAction: string;
+    };
+}>;
+export declare function clearStaleSetupLock(workspace: string): Promise<void>;
+declare function runDocumentGranularCompanion(input: {
+    root: string;
+    plan: ResearchSetupPlan;
+    skill: ResearchSetupSkill;
+    skillDirectory: string;
+    credentialDefinitions: ResearchSetupCredential[];
+    credentials: Map<string, string>;
+    input: Extract<ResearchSetupCompanionInput, {
+        skillId: "tiangong.document-granular-decompose";
+    }>;
+    environment: NodeJS.ProcessEnv;
+    runner: SetupCommandRunner;
+}): Promise<{
+    schemaVersion: 1;
+    kind: "research-setup-companion-result";
+    status: "complete";
+    workspace: string;
+    skillId: string;
+    role: import("./setup-catalog.js").ResearchSetupRole;
+    input: {
+        path: string;
+        sha256: string;
+        bytes: number;
+    };
+    output: {
+        path: string;
+        sha256: string;
+        bytes: number;
+    };
+    provenance: {
+        planSha256: string;
+        sourceId: string;
+        sourceRef: string;
+        skillTreeSha256: string;
+    };
+    next: string;
+}>;
+declare function runAcademicPaperCompanion(input: {
+    root: string;
+    plan: ResearchSetupPlan;
+    skill: ResearchSetupSkill;
+    skillDirectory: string;
+    credentials: Map<string, string>;
+    input: Extract<ResearchSetupCompanionInput, {
+        skillId: "tiangong.academic-paper-download";
+    }>;
+    environment: NodeJS.ProcessEnv;
+    runner: SetupCommandRunner;
+}): Promise<{
+    schemaVersion: 1;
+    kind: "research-setup-companion-result";
+    status: "browser-handoff-required";
+    workspace: string;
+    skillId: string;
+    role: import("./setup-catalog.js").ResearchSetupRole;
+    artifactCommitted: boolean;
+    sourcesTried: any[];
+    error: Record<string, unknown>;
+    provenance: {
+        planSha256: string;
+        sourceId: string;
+        sourceRef: string;
+        skillTreeSha256: string;
+    };
+    next: string;
+    artifact?: never;
+    manifest?: never;
+    source?: never;
+    validation?: never;
+} | {
+    schemaVersion: 1;
+    kind: "research-setup-companion-result";
+    status: "complete";
+    workspace: string;
+    skillId: string;
+    role: import("./setup-catalog.js").ResearchSetupRole;
+    artifact: {
+        path: string;
+        sha256: string;
+        bytes: number;
+    };
+    manifest: {
+        path: string;
+        sha256: string;
+        bytes: number;
+    };
+    source: string | null;
+    provenance: {
+        planSha256: string;
+        sourceId: string;
+        sourceRef: string;
+        skillTreeSha256: string;
+    };
+    validation: string[];
+    next: string;
+    artifactCommitted?: never;
+    sourcesTried?: never;
+    error?: never;
+}>;
+export {};