ISPO SDK
    Preparing search index...

    Interface HostApi

    Markdown
    interface HostApi {
        capabilities: { list(): Promise<HostCapabilitySurface> };
        evaluations: {
            beginFolderSelection(
                input?: EvaluationFolderSelectionInput,
            ): Promise<EvaluationFolderSelection | null>;
            createWork(
                input: EvaluationWorkCreateInput,
            ): Promise<EvaluationWorkCreateResult>;
            getRemediation(
                input: EvaluationRemediationStatusInput,
            ): Promise<EvaluationRemediationStatus | null>;
            getRun(input: EvaluationRunGetInput): Promise<EvaluationRunGetResult>;
            listRuns(input?: EvaluationRunListInput): Promise<EvaluationRunListResult>;
            listWorkRoots(
                input?: EvaluationWorkRootListInput,
            ): Promise<readonly EvaluationWorkRootCatalogEntry[]>;
            request(
                input: EvaluationRunRequestInput,
            ): Promise<EvaluationRunRequestResult>;
            rerun(input: EvaluationRunRerunInput): Promise<EvaluationRunDetail>;
            startRemediation(
                input: EvaluationRemediationStartInput,
            ): Promise<EvaluationRemediationStartResult>;
        };
        icons: {
            cancelCreate(): Promise<void>;
            create(input: HostIconsCreateInput): Promise<HostIconsCreateResult>;
        };
        projectIcons: {
            catalog(): Promise<HostProjectIconCatalogSnapshot>;
            delete(
                input: HostProjectIconDeleteInput,
            ): Promise<HostProjectIconDeleteResult | null>;
            set(input: HostProjectIconSetInput): Promise<HostProjectIconAssignment>;
            setMany(
                input: HostProjectIconSetManyInput,
            ): Promise<HostProjectIconSetManyResult>;
            targets(): Promise<HostProjectIconTargetsResult>;
            watchCatalog(
                input: HostProjectIconCatalogWatchInput,
            ): Promise<HostProjectIconCatalogSnapshot>;
        };
        projects: { list(): Promise<HostProjectSummary[]> };
        sounds: {
            catalog(): Promise<HostSoundCatalogSnapshot>;
            set(input: HostSoundSetInput): Promise<HostSoundAssignment>;
            setMany(input: HostSoundSetManyInput): Promise<HostSoundSetManyResult>;
            targets(): Promise<HostSoundTargetsResult>;
            watchCatalog(
                input: HostSoundCatalogWatchInput,
            ): Promise<HostSoundCatalogSnapshot>;
        };
        spec: {
            listSections(): Promise<HostSpecSectionSummary[]>;
            readSection(
                input: HostSpecSectionReadInput,
            ): Promise<HostSpecSectionContent>;
        };
        composeInChat(prompt: string): void;
        navigate(input: HostNavigateInput): Promise<void>;
        onNavigate(handler: HostNavigateHandler): () => void;
        openCreateProjectDraft(input: HostCreateProjectDraftInput): void;
        openExternal(url: string): Promise<void>;
        proposeSpecEdits(input: ProposeSpecEditsInput): void;
    }
    Index
    capabilities evaluations icons projectIcons projects sounds spec
    composeInChat navigate onNavigate openCreateProjectDraft openExternal proposeSpecEdits
    capabilities: { list(): Promise<HostCapabilitySurface> }

    Type Declaration

    • list: function
      • list(): Promise<HostCapabilitySurface>

        The platform capability vocabulary plus THIS project's own envelope (§10.33). Grantless, argument-free, and inert: every project method with the declaration token and grant capability its gates read, the connector providers and host catalog selectors, device features, built-in entity types, and a self block with the caller's reviewed requests, live grants, and trust class.

        Use it to render an honest blocked state — "Calendar write isn't granted yet" with a one-click ask — instead of discovering a missing grant from a failed call. It discloses no other project's envelope and grants nothing: a listed method still faces both gates when you call it.

        Returns Promise<HostCapabilitySurface>

    evaluations: {
        beginFolderSelection(
            input?: EvaluationFolderSelectionInput,
        ): Promise<EvaluationFolderSelection | null>;
        createWork(
            input: EvaluationWorkCreateInput,
        ): Promise<EvaluationWorkCreateResult>;
        getRemediation(
            input: EvaluationRemediationStatusInput,
        ): Promise<EvaluationRemediationStatus | null>;
        getRun(input: EvaluationRunGetInput): Promise<EvaluationRunGetResult>;
        listRuns(input?: EvaluationRunListInput): Promise<EvaluationRunListResult>;
        listWorkRoots(
            input?: EvaluationWorkRootListInput,
        ): Promise<readonly EvaluationWorkRootCatalogEntry[]>;
        request(
            input: EvaluationRunRequestInput,
        ): Promise<EvaluationRunRequestResult>;
        rerun(input: EvaluationRunRerunInput): Promise<EvaluationRunDetail>;
        startRemediation(
            input: EvaluationRemediationStartInput,
        ): Promise<EvaluationRemediationStartResult>;
    }

    Type Declaration

    icons: {
        cancelCreate(): Promise<void>;
        create(input: HostIconsCreateInput): Promise<HostIconsCreateResult>;
    }

    Bundled-Icons-only generated-icon transaction. Main owns provider egress, secret resolution, durable persistence, and Asset publication.

    Type Declaration

    projectIcons: {
        catalog(): Promise<HostProjectIconCatalogSnapshot>;
        delete(
            input: HostProjectIconDeleteInput,
        ): Promise<HostProjectIconDeleteResult | null>;
        set(input: HostProjectIconSetInput): Promise<HostProjectIconAssignment>;
        setMany(
            input: HostProjectIconSetManyInput,
        ): Promise<HostProjectIconSetManyResult>;
        targets(): Promise<HostProjectIconTargetsResult>;
        watchCatalog(
            input: HostProjectIconCatalogWatchInput,
        ): Promise<HostProjectIconCatalogSnapshot>;
    }

    Type Declaration

    Authority for host.projectIcons

    Reviewed request token: chrome.project-icons. Standing capability: projectIcons.manage.

    Handle structured ProjectRpcError failures. A timeout does not guarantee cancellation; do not automatically retry effects without a documented idempotency contract. Method authority and recovery.

    projects: { list(): Promise<HostProjectSummary[]> }

    Type Declaration

    • list: function
      • list(): Promise<HostProjectSummary[]>

        List registered projects for a picker. Read-only and grantless; the result intentionally contains no project roots or authority metadata.

        Returns Promise<HostProjectSummary[]>

    sounds: {
        catalog(): Promise<HostSoundCatalogSnapshot>;
        set(input: HostSoundSetInput): Promise<HostSoundAssignment>;
        setMany(input: HostSoundSetManyInput): Promise<HostSoundSetManyResult>;
        targets(): Promise<HostSoundTargetsResult>;
        watchCatalog(
            input: HostSoundCatalogWatchInput,
        ): Promise<HostSoundCatalogSnapshot>;
    }

    Type Declaration

    • catalog: function
      • catalog(): Promise<HostSoundCatalogSnapshot>

        Read the canonical UI-sound catalog (every accepted ui-sound asset). Requires requests.chrome: ["host-sound-catalog"] and the hostSounds.manage grant; catalog access does not by itself request assignment.

        Returns Promise<HostSoundCatalogSnapshot>

    • set: function
      • set(input: HostSoundSetInput): Promise<HostSoundAssignment>

        Assign or clear the host UI sound for one slot (soundRef: null clears back to the host default). Requires requests.chrome: ["host-sounds"] and the hostSounds.manage grant. The host validates the ref is an accepted ui-sound asset (PCM WAV, ≤ 3s, ≤ 2MB) at assignment time.

        Parameters

        Returns Promise<HostSoundAssignment>

    • setMany: function
    • targets: function
      • targets(): Promise<HostSoundTargetsResult>

        List the host sound slots (id, label, description, current soundRef). The slot vocabulary is closed and host-owned; treat this as the runtime authority rather than hardcoding HostSoundSlotId. Same requests.chrome: ["host-sounds"] + hostSounds.manage gate as set.

        Returns Promise<HostSoundTargetsResult>

    • watchCatalog: function
    spec: {
        listSections(): Promise<HostSpecSectionSummary[]>;
        readSection(
            input: HostSpecSectionReadInput,
        ): Promise<HostSpecSectionContent>;
    }

    Type Declaration

    • Hand a prompt to the host Chat pane: the host seeds the currently selected chat/draft composer with prompt and focuses it (does not start a new chat). Fire-and-forget (a host-chrome trigger, NOT an RPC — there is no reply). The user still presses Send; a sandboxed project can never make the assistant act on its own, so this is not gated by a device/consent grant — the human Send is the trust boundary. A no-op when not embedded (window.parent === window) or when prompt is empty. Only honored for the currently active project's chat. Use it to demonstrate or seed a "change this app" prompt in-product.

      Parameters

      • prompt: string

      Returns void

    • Request coarse host navigation (needs "navigate" in requests.ui; cross-project also needs the ui.navigate grant, same-project does not). To bring the user to an EXACT agent terminal — e.g. the one you just agent.spawn-ed — pass { kind: 'agents', terminalId } with the spawn result's terminalId (focuses it directly, no entity round-trip); terminalSessionId focuses by the terminal.session entity id instead, and a bare { kind: 'agents' } opens the panel.

      Parameters

      Returns Promise<void>

    Authority for host.navigate

    Reviewed request token: ui.navigate. Authority depends on the arguments, resource, and caller; check the live capability surface.

    Handle structured ProjectRpcError failures. A timeout does not guarantee cancellation; do not automatically retry effects without a documented idempotency contract. Method authority and recovery.

    • Open the host Create intake with an editable title and prompt. This is a host-chrome trigger, not project-creation authority: the host attributes the sender, and the user still deliberately submits the intake.

      Parameters

      Returns void

    • Open an HTTP(S) URL in the persistent ISPO Browser. Grantless but trust-gated: allowed for workspace/privileged-workspace projects, rejected with host.openExternal: trust-blocked for quarantined/sandboxed ones, and rejected for non-http(s) URLs. Plain <a href> clicks to external URLs are routed here automatically by connectToHost(), so call this only for programmatic opens (buttons, card clicks). Never navigate window.location to an external URL — the host CSP kills that navigation and blanks the app frame.

      Parameters

      • url: string

      Returns Promise<void>

    Authority for host.openExternal

    No static request token. No static standing capability. Resource bindings, identity checks, or interactive consent may still apply.

    Handle structured ProjectRpcError failures. A timeout does not guarantee cancellation; do not automatically retry effects without a documented idempotency contract. Method authority and recovery.

    • Propose per-file spec edits to host chrome (Spec → live document, Phase 3). Fire-and-forget: posts a spec-propose-edits wire frame to the host. disposition: 'review' (default) opens the diff modal; disposition: 'save' commits immediately under the user's Save click (no modal / no agent). Commit is still host-owned and gated by spec.propose — not an RPC. Only the bundled/privileged spec project uses it.

      Parameters

      Returns void

    Settings
    Member Visibility

    On This Page
    Properties
    Methods