@hosty-sdk/app 0.37.0 → 0.39.0

package/dist/feedback-types.d.ts

@@ -0,0 +1,122 @@
+export type FeedbackRect = {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+};
+export type FeedbackTarget = {
+    kind: "element" | "region" | "page";
+    label?: string;
+    selector?: string;
+    bounds?: FeedbackRect;
+    viewport?: {
+        width: number;
+        height: number;
+        scale: number;
+    };
+};
+export type FeedbackNoteInput = {
+    id: string;
+    text: string;
+    route: string;
+    capturedAt: string;
+    target?: FeedbackTarget;
+    image?: {
+        mediaType: string;
+        data: string;
+    };
+};
+export type FeedbackSubmit = {
+    requestId: string;
+    comment: string;
+    annotations: FeedbackNoteInput[];
+    scope?: {
+        coreId: string;
+        appId: string;
+        installation: string;
+        userId: string;
+    };
+};
+export type FeedbackCapabilities = {
+    version: 1;
+    coreId: string;
+    appId: string;
+    installation: string;
+    userId: string;
+    maxAnnotations: number;
+    maxImageBytes: number;
+    maxTotalImageBytes: number;
+    administrator?: boolean;
+};
+export type FeedbackNote = Omit<FeedbackNoteInput, "image"> & {
+    mediaType: string | null;
+};
+export type FeedbackReport = {
+    id: string;
+    reporterId: string;
+    comment: string;
+    annotations: FeedbackNote[];
+    context: {
+        appId: string;
+        appName: string;
+        installation: string;
+        version: string | null;
+        observedAt: string;
+        executionKind: string;
+        workspaceId: string | null;
+        sourceRevision: string | null;
+    };
+    workspaceId: string | null;
+    revision: number;
+    status: string;
+    currentAttemptId: string | null;
+    disposition: string | null;
+};
+export type FeedbackSelection = {
+    id: string;
+    revision: number;
+};
+export type FeedbackDispatchInput = {
+    requestId: string;
+    sessionId: string;
+    workspaceId: string | null;
+    reports: FeedbackSelection[];
+    instruction: string;
+    appContextRevision?: number;
+    selectionRevision?: number;
+};
+export type FeedbackOutcome = {
+    reportId: string;
+    summary: string;
+    handledAnnotationIds: string[];
+    handled: boolean;
+};
+export type FeedbackDispatch = {
+    id: string;
+    callerAppId: string;
+    callerInstallation: string;
+    actorId: string;
+    input: FeedbackDispatchInput;
+    snapshot: FeedbackReport[];
+    createdAt: string;
+    state: string;
+    messageSequence: number | null;
+    workspaceId: string | null;
+    outcomes: FeedbackOutcome[] | null;
+    error: string | null;
+};
+export type FeedbackCollection = {
+    reports: FeedbackReport[];
+    dispatches: FeedbackDispatch[];
+};
+export type FeedbackDelivery = {
+    state: string;
+    messageSequence?: number;
+    workspaceId?: string | null;
+    error?: string;
+};
+export declare class FeedbackError extends Error {
+    readonly code: string;
+    readonly status: number;
+    constructor(code: string, message: string, status: number);
+}

package/dist/feedback-types.js

@@ -0,0 +1,9 @@
+export class FeedbackError extends Error {
+    code;
+    status;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}

package/dist/history.d.ts

@@ -0,0 +1,354 @@
+import type { ConversationRef, NativeSessionRef, ProviderRef, Revision, RunRef } from "./agent-sessions.js";
+export type { ConversationRef, NativeSessionRef, ProviderRef, Revision, RunRef } from "./agent-sessions.js";
+export type EntryRef = {
+    conversation: ConversationRef;
+    id: string;
+};
+export type HistoryCoverage = {
+    state: "complete" | "partial";
+    reasons: string[];
+};
+export type Conversation = {
+    ref: ConversationRef;
+    revision: Revision;
+    title: string | null;
+    ownerUserId: string;
+    createdAt: string;
+    updatedAt: string;
+    nativeSessions?: NativeSessionRef[];
+    capabilities: string[];
+};
+export type HistoryPart = {
+    type: "text";
+    text: string;
+    format: "plain" | "markdown";
+} | {
+    type: "attachment";
+    attachmentId: string;
+    revision: Revision;
+    mediaType: string;
+    name: string;
+    sizeBytes?: number;
+} | {
+    type: "resource";
+    resourceKind: string;
+    owner: string;
+    id: string;
+    revision?: Revision;
+    label?: string;
+};
+export type Disclosure = "complete" | "redacted" | "truncated";
+export type HistoryData = {
+    kind: "message";
+    role: "user" | "assistant" | "system";
+    parts: HistoryPart[];
+    state: "streaming" | "complete" | "interrupted";
+} | {
+    kind: "tool_call";
+    callId: string;
+    toolName: string;
+    input: unknown;
+    disclosure: Disclosure;
+} | {
+    kind: "tool_result";
+    callId: string;
+    parts: HistoryPart[];
+    outcome: "completed" | "failed" | "cancelled" | "unknown";
+    durationMs?: number;
+    disclosure: Disclosure;
+} | {
+    kind: "run_state";
+    state: string;
+    stopConfirmed: boolean;
+} | {
+    kind: "usage";
+    scope: "turn" | "run";
+    source: string;
+    inputTokens?: number;
+    outputTokens?: number;
+    cachedInputTokens?: number;
+    estimated: boolean;
+    cost?: {
+        amount: string;
+        currency: string;
+    };
+} | {
+    kind: "extension";
+    name: string;
+    version: number;
+    payload: unknown;
+    fallbackText?: string;
+    disclosure: Disclosure;
+};
+export type HistoryKind = HistoryData["kind"];
+export type HistoryEntry = {
+    ref: EntryRef;
+    revision: Revision;
+    sequence: Revision;
+    createdAt: string;
+    updatedAt: string;
+    actor: {
+        kind: "user" | "agent" | "system" | "tool";
+        id?: string;
+        displayName?: string;
+    };
+    run?: RunRef;
+    parentEntryId?: string;
+    data: HistoryData;
+};
+export type HistoryExtension = {
+    name: string;
+    version: number;
+    schema: Record<string, unknown>;
+};
+export type HistoryCapabilities = {
+    version: 1;
+    entryKinds: HistoryKind[];
+    extensions: HistoryExtension[];
+    maxPageSize: number;
+    snapshotLifetimeSeconds: number;
+    changeRetentionSeconds: number;
+};
+export type ConversationQuery = {
+    providers: ProviderRef[];
+    title?: string;
+    cursor?: string;
+    limit?: number;
+};
+export type SourceConversationQuery = {
+    provider: ProviderRef;
+    title?: string;
+    cursor?: string;
+    limit?: number;
+};
+export type ConversationPage = {
+    conversations: Conversation[];
+    nextCursor: string | null;
+    coverage: HistoryCoverage;
+    providers: HistoryProviderCoverage[];
+};
+export type SourceConversationPage = {
+    conversations: Conversation[];
+    nextCursor: string | null;
+    snapshotId: string;
+    highWater: Revision;
+    coverage: HistoryCoverage;
+};
+export type HistoryQuery = {
+    conversation: ConversationRef;
+    kinds?: HistoryKind[];
+    cursor?: string;
+    limit?: number;
+};
+export type HistoryPage = {
+    entries: HistoryEntry[];
+    nextCursor: string | null;
+    snapshotId: string;
+    highWater: Revision;
+    coverage: HistoryCoverage;
+};
+export type HistoryEntryGet = {
+    entry: EntryRef;
+    expectedRevision?: Revision;
+};
+export type HistorySearch = {
+    providers?: ProviderRef[];
+    q: string;
+    kinds?: HistoryKind[];
+    conversations?: ConversationRef[];
+    cursor?: string;
+    limit?: number;
+};
+export type HistorySearchHit = {
+    entry: EntryRef;
+    revision: Revision;
+    conversationTitle: string | null;
+    excerpt: string;
+    updatedAt: string;
+    observedAt: string;
+};
+export type HistoryProviderCoverage = {
+    provider: ProviderRef;
+    state: "complete" | "partial" | "unavailable" | "unsupported";
+    error?: HistoryError;
+};
+export type HistorySearchPage = {
+    hits: HistorySearchHit[];
+    nextCursor: string | null;
+    coverage: HistoryCoverage;
+    providers: HistoryProviderCoverage[];
+};
+export type HistorySelection = {
+    entryIds?: string[];
+    includeFutureEntries?: true;
+};
+export type HistoryShareCreate = {
+    ref: ConversationRef;
+    requestId: string;
+    expectedRevision: Revision;
+    selection: HistorySelection;
+    recipientUserIds: string[];
+    includeAttachments: boolean;
+    extensions?: string[];
+    label?: string;
+    expiresAt?: string;
+};
+export type HistoryShare = {
+    id: string;
+    ref: ConversationRef;
+    revision: Revision;
+    ownerUserId: string;
+    recipientUserIds: string[];
+    selection: HistorySelection;
+    includeAttachments: boolean;
+    extensions: string[];
+    label: string | null;
+    expiresAt: string | null;
+    state: "active" | "revoked";
+};
+export type HistoryShareRevoke = {
+    ref: ConversationRef;
+    grantId: string;
+    requestId: string;
+    expectedRevision: Revision;
+};
+export type HistorySharePage = {
+    shares: HistoryShare[];
+    conversationRevision: Revision;
+};
+export type HistoryShareReceipt = {
+    requestId: string;
+    grant: HistoryShare;
+    conversationRevision: Revision;
+};
+export type HistoryAttachmentResolve = {
+    entry: EntryRef;
+    attachmentId: string;
+    revision: Revision;
+};
+export type HistoryAttachment = {
+    attachmentId: string;
+    revision: Revision;
+    name: string;
+    mediaType: string;
+    sizeBytes: number;
+    handle: string;
+    expiresAt: string;
+};
+export type HistoryExportCorpus = {
+    mode: "all-owned";
+    includeFutureConversations: true;
+    providers: ProviderRef[];
+} | {
+    mode: "conversations";
+    conversations: ConversationRef[];
+};
+export type HistoryExportConsumer = {
+    kind: "self";
+} | {
+    kind: "app";
+    appId: string;
+    installationId: string;
+};
+export type HistoryExportCreate = {
+    requestId: string;
+    consumer: HistoryExportConsumer;
+    corpus: HistoryExportCorpus;
+    purpose: string;
+    expiresAt?: string;
+};
+export type HistoryExportGrant = {
+    id: string;
+    revision: Revision;
+    ownerUserId: string;
+    consumer: HistoryExportConsumer;
+    principalId: string;
+    corpus: HistoryExportCorpus;
+    purpose: string;
+    expiresAt: string | null;
+    state: "proposed" | "active";
+    approvalUrl?: string | null;
+    lastAppliedCursor?: string | null;
+} | {
+    id: string;
+    revision: Revision;
+    state: "purge_required" | "purged";
+    ownerUserId?: string | null;
+    consumer?: HistoryExportConsumer | null;
+    principalId?: string | null;
+    corpus?: HistoryExportCorpus | null;
+    purpose?: string | null;
+    expiresAt?: string | null;
+    approvalUrl?: null;
+    lastAppliedCursor?: string | null;
+};
+export type HistoryExportQuery = {
+    exportGrantId: string;
+    provider: ProviderRef;
+    cursor?: string;
+    limit?: number;
+};
+export type HistoryExportSnapshot = {
+    entries: HistoryEntry[];
+    nextCursor: string | null;
+    snapshotId: string;
+    highWater: Revision;
+    changeCursor: string;
+    coverage: HistoryCoverage;
+};
+export type HistoryChange = {
+    id: string;
+    sequence: Revision;
+    type: "upsert";
+    entry: HistoryEntry;
+} | {
+    id: string;
+    sequence: Revision;
+    type: "delete";
+    ref: EntryRef;
+    revision: Revision;
+} | {
+    id: string;
+    sequence: Revision;
+    type: "access_reset";
+    reason: string;
+};
+export type HistoryChangePage = {
+    changes: HistoryChange[];
+    nextCursor: string;
+    highWater: Revision;
+    coverage: HistoryCoverage;
+};
+export type HistoryExportAcknowledge = {
+    exportGrantId: string;
+    requestId: string;
+    expectedRevision: Revision;
+    lastAppliedCursor?: string;
+    purgeComplete?: boolean;
+};
+export type HistoryError = {
+    code: string;
+    message: string;
+    retryable: boolean;
+    operationRef?: string;
+};
+export type HistoryNotification = {
+    conversation: ConversationRef;
+    revision: Revision;
+    cursor: string;
+    changes: Array<{
+        type: "upsert" | "delete";
+        entryId: string;
+        revision: Revision;
+    }>;
+    rescanRequired: boolean;
+};
+export type HistorySubscription = {
+    handle: string;
+    expiresAt: string;
+    initial: HistoryNotification;
+};
+export type HistorySubscriptionCreate = {
+    conversation: ConversationRef;
+    cursor?: string;
+};

package/dist/history.js

@@ -0,0 +1 @@
+export {};

package/dist/providers-server.d.ts

@@ -1,5 +1,6 @@
+import type { HistoryExportGrant, HistoryExportAcknowledge, HistoryExportQuery, HistoryExportSnapshot, HistoryChangePage } from "./history.js";
 import { AssistantClient } from "@hosty-sdk/app/assistant";
-import { type AppPermissionState, type ProviderDescriptor, type ProviderInvocation, type ProviderKind, type SpeechCapabilities, type SpeechResult, type TranslationRequest, type TranslationResult, type TranslationCapabilities } from "@hosty-sdk/app/providers";
+import { type AppPermissionState, type ProviderDescriptor, type ProviderInvocation, type ProviderKind, type MediatedProviderInvocation, type MediatedProviderRequest, type SpeechCapabilities, type SpeechResult, type TranslationRequest, type TranslationResult, type TranslationCapabilities } from "@hosty-sdk/app/providers";
 export type ProviderServerOptions = {
     appId?: string;
     coreOrigin?: string;
@@ -15,6 +16,19 @@ export declare class ProviderClient {
     private readonly container;
     constructor(options?: ProviderServerOptions);
     private coreRequest;
+    /** Recover only an already-authorized immutable task attempt; service identity alone grants no user authority. */
+    taskDispatch<T>(input: import("./providers.js").TaskDispatchRequest, signal?: AbortSignal): Promise<T>;
+    /** No general user/source credential is minted; the original attempt and grants remain authoritative. */
+    taskWorkspace<T>(input: import("./providers.js").TaskWorkspaceRequest, signal?: AbortSignal): Promise<T>;
+    taskDispatchAuthority(dispatch: import("./providers.js").TaskDispatchRef, signal?: AbortSignal): Promise<{
+        dispatch: import("./providers.js").TaskDispatchRef;
+        scope: import("./providers.js").TaskDispatchScope;
+    }>;
+    /** The service identity accesses only export grants explicitly approved for this installation. */
+    historyExportGet(exportGrantId: string, signal?: AbortSignal): Promise<HistoryExportGrant>;
+    historyExportAcknowledge(input: HistoryExportAcknowledge, signal?: AbortSignal): Promise<HistoryExportGrant>;
+    historyExportSnapshot(input: HistoryExportQuery, signal?: AbortSignal): Promise<HistoryExportSnapshot>;
+    historyExportChanges(input: HistoryExportQuery, signal?: AbortSignal): Promise<HistoryChangePage>;
     permissions(signal?: AbortSignal): Promise<AppPermissionState>;
     list(kind: ProviderKind, signal?: AbortSignal): Promise<ProviderDescriptor[]>;
     private connect;
@@ -32,6 +46,8 @@ export declare class ProviderClient {
     }, userToken: () => Promise<string>): Promise<AssistantClient>;
     /** Bounded task protocol transport. The selected installation is checked on every operation. */
     taskRequest<T>(provider: import("./tasks.js").TaskProviderRef, kind: "tasks" | "task-executor", route: string, method: string, input?: unknown, userToken?: () => Promise<string>, signal?: AbortSignal): Promise<T>;
+    /** Validate an operation-bound Core credential against this exact request. Source ACL checks remain mandatory. */
+    validateMediated(token: string, kind: ProviderKind, request: MediatedProviderRequest, key?: string, signal?: AbortSignal): Promise<MediatedProviderInvocation>;
     /** Provider-side validation checks live grants on every request; never cache this result. */
     validate(token: string, kind: ProviderKind, key?: string, signal?: AbortSignal): Promise<ProviderInvocation>;
 }

package/dist/providers-server.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { AssistantClient } from "@hosty-sdk/app/assistant";
 import { ProviderError } from "@hosty-sdk/app/providers";
 /** Server-only provider client. Its app service token must never be sent to a browser or provider. */
@@ -23,6 +24,22 @@ export class ProviderClient {
         });
         return read(response);
     }
+    /** Recover only an already-authorized immutable task attempt; service identity alone grants no user authority. */
+    taskDispatch(input, signal) {
+        return this.coreRequest("/task-dispatch", input, signal);
+    }
+    /** No general user/source credential is minted; the original attempt and grants remain authoritative. */
+    taskWorkspace(input, signal) {
+        return this.coreRequest("/task-workspace", input, signal);
+    }
+    taskDispatchAuthority(dispatch, signal) {
+        return this.coreRequest("/task-dispatch-authority", { dispatch }, signal);
+    }
+    /** The service identity accesses only export grants explicitly approved for this installation. */
+    historyExportGet(exportGrantId, signal) { return this.coreRequest("/history-exports/get", { exportGrantId }, signal); }
+    historyExportAcknowledge(input, signal) { return this.coreRequest("/history-exports/acknowledge", input, signal); }
+    historyExportSnapshot(input, signal) { return this.coreRequest("/history-exports/snapshot", input, signal); }
+    historyExportChanges(input, signal) { return this.coreRequest("/history-exports/changes", input, signal); }
     permissions(signal) { return this.coreRequest("/permissions", undefined, signal); }
     async list(kind, signal) {
         return (await this.coreRequest(`/providers/${kind}`, undefined, signal)).providers;
@@ -92,6 +109,20 @@ export class ProviderClient {
             headers: { authorization: `Bearer ${binding.token}`, "content-type": "application/json" },
             body: input === undefined ? undefined : JSON.stringify(input) }));
     }
+    /** Validate an operation-bound Core credential against this exact request. Source ACL checks remain mandatory. */
+    async validateMediated(token, kind, request, key = "default", signal) {
+        if (!token.startsWith("hosty_provider.2.") || !request.path.startsWith("/") || request.path.startsWith("//")
+            || !["GET", "POST", "PATCH", "PUT", "DELETE"].includes(request.method) || Buffer.byteLength(request.body) > 1024 * 1024)
+            throw new ProviderError("token_invalid", "A bounded, exact Core-mediated provider request is required.", 401);
+        const invocation = await this.coreRequest("/provider/introspect-v2", {
+            token, kind, key, operation: request.operation, method: request.method, path: request.path,
+            bodyHash: createHash("sha256").update(request.body).digest("hex"),
+        }, signal);
+        if (invocation.version !== 2 || invocation.kind !== kind || invocation.key !== key || invocation.operation !== request.operation
+            || !invocation.userId || !invocation.principalId || !Array.isArray(invocation.resourceIds))
+            throw new ProviderError("token_invalid", "Core returned an invalid mediated invocation.", 401);
+        return invocation;
+    }
     /** Provider-side validation checks live grants on every request; never cache this result. */
     validate(token, kind, key = "default", signal) {
         return this.coreRequest("/provider/introspect", { token, kind, key }, signal);
@@ -99,8 +130,9 @@ export class ProviderClient {
 }
 async function read(response) {
     const body = await response.json().catch(() => null);
+    const error = body?.error ?? body;
     if (!response.ok)
-        throw new ProviderError(body?.code ?? "provider_failed", body?.message ?? `Provider request failed (${response.status}).`, response.status);
+        throw new ProviderError(error?.code ?? "provider_failed", error?.message ?? `Provider request failed (${response.status}).`, response.status);
     if (body === null)
         throw new ProviderError("provider_response_invalid", "Provider returned an invalid response.", 502);
     return body;

package/dist/providers.d.ts

@@ -1,5 +1,5 @@
 /** Provider categories supported by Core. Task execution does not expose model/profile configuration. */
-export type ProviderKind = "speech-to-text" | "assistant" | "translation" | "tasks" | "task-executor";
+export type ProviderKind = "speech-to-text" | "assistant" | "translation" | "tasks" | "task-executor" | "conversation-history" | "agent-sessions";
 export type ProviderDescriptor = {
     appId: string;
     displayName: string;
@@ -36,6 +36,39 @@ export type ProviderInvocation = {
     kind: ProviderKind;
     key: string;
 };
+/** Core-mediated v2 invocations carry the original principal; direct clients have no app identity. */
+export type MediatedProviderInvocation = {
+    version: 2;
+    callerAppId: string | null;
+    callerInstallation: string | null;
+    userId: string;
+    hostRole: string;
+    principalId: string;
+    kind: ProviderKind;
+    key: string;
+    operation: string;
+    resourceIds: string[];
+    taskDispatch?: TaskDispatchRef | null;
+    taskDelegation?: {
+        dispatch: TaskDispatchRef;
+        taskRef: import("./tasks.js").TaskRef;
+        executionId: string | null;
+    } | null;
+    export?: {
+        grantId: string;
+        revision: string;
+        ownerUserId: string;
+        provider: import("./agent-sessions.js").ProviderRef;
+        conversationIds: string[] | null;
+    } | null;
+};
+/** The provider computes these values from the actual incoming request, never from unverified claims. */
+export type MediatedProviderRequest = {
+    operation: string;
+    method: string;
+    path: string;
+    body: Uint8Array | string;
+};
 export type SpeechResult = {
     text: string;
     language?: string | null;
@@ -77,3 +110,45 @@ export declare class ProviderError extends Error {
     readonly status: number;
     constructor(code: string, message: string, status: number);
 }
+/** Non-secret receipt reference. Only its reviewed source and executor installations can use it. */
+export type TaskDispatchRef = {
+    userId: string;
+    principalId: string;
+    requestId: string;
+};
+export type TaskDispatchScope = {
+    taskRef: import("./tasks.js").TaskRef;
+    executor: import("./tasks.js").TaskProviderRef;
+    inputRevision: number;
+    inputHash: string;
+    optionId: string | null;
+    executionId: string | null;
+    workspaceId?: string | null;
+};
+export type TaskDispatchRequest = {
+    dispatch: TaskDispatchRef;
+    executor: import("./tasks.js").TaskProviderRef;
+    operation: "options" | "get" | "accept" | "cancel";
+    executionId?: string;
+    input?: import("./tasks.js").TaskExecutionInput;
+    requestId?: string;
+};
+/** Executor-only access to the workspace already selected by an immutable task attempt. */
+export type TaskWorkspaceRequest = {
+    dispatch: TaskDispatchRef;
+    executionId: string;
+    sessionId: string;
+    leaseId: string;
+    kind: "observe" | "attach" | "lease" | "activity";
+    requestId?: string;
+    expectedRevision?: number;
+    title?: string;
+    navigationPath?: string;
+    activity?: {
+        status: string;
+        leaseId: string;
+        stopped?: boolean;
+        title?: string;
+        sequence?: number;
+    };
+};

package/dist/tasks-server.d.ts

@@ -31,3 +31,14 @@ export declare class TaskExecutorClient {
     get(executionId: string, signal?: AbortSignal): Promise<TaskExecutionReceipt>;
     cancel(executionId: string, requestId: string, signal?: AbortSignal): Promise<TaskExecutionReceipt>;
 }
+/** Core-mediated child calls retain the original caller and the exact task-provider attribution. */
+export declare class MediatedTaskExecutorClient {
+    private readonly providers;
+    private readonly executor;
+    private readonly dispatch;
+    constructor(providers: ProviderClient, executor: TaskProviderRef, dispatch: import("./providers.js").TaskDispatchRef);
+    options(signal?: AbortSignal): Promise<TaskExecutorOptions>;
+    get(executionId: string, signal?: AbortSignal): Promise<TaskExecutionReceipt>;
+    accept(executionId: string, input: TaskExecutionInput, signal?: AbortSignal): Promise<TaskExecutionReceipt>;
+    cancel(executionId: string, requestId: string, signal?: AbortSignal): Promise<TaskExecutionReceipt>;
+}