dexto 1.14.5 → 2.0.0-beta.0

package/dist/cli/cloud/commands/workspace.d.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod';
+import { type Command, type CommandContext } from '../command.js';
+declare const ToolSchema: z.ZodObject<{
+    _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    description: z.ZodOptional<z.ZodString>;
+    inputSchema: z.ZodUnknown;
+    name: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type WorkspaceTool = z.output<typeof ToolSchema>;
+/** The levels at which a call asks the person before it runs. */
+export declare const ASKING_LEVELS: ReadonlySet<string>;
+/** A tool's level for one call: its action's own level, where the action decides it. */
+export declare function toolCallLevel(tool: WorkspaceTool, input: Record<string, unknown>): string;
+/**
+ * Agrees to a call that asks first, by `--yes` or at the terminal, and returns what to add to its
+ * input: `confirm: true` where the tool takes it, the server's sign that the person agreed.
+ */
+export declare function agreeToCall(context: CommandContext, call: {
+    readonly level: string;
+    readonly schema: unknown;
+    readonly title: string;
+}, yes: boolean): Promise<{
+    confirm?: true;
+}>;
+/** Every workspace tool the sign-in can call, as the Dexto MCP lists them. */
+export declare function listWorkspaceTools(context: CommandContext): Promise<WorkspaceTool[]>;
+/** Calls a workspace tool and prints its result; a tool's own error fails the command. */
+export declare function callWorkspaceTool(context: CommandContext, name: string, input: unknown): Promise<number>;
+/** Calls a workspace tool for its value, without printing it; the tool's own error fails. */
+export declare function queryWorkspaceTool(context: CommandContext, name: string, input: unknown): Promise<unknown>;
+/** Calls a workspace tool for its structured result, without printing it. */
+export declare function readWorkspaceTool(context: CommandContext, name: string, input: unknown): Promise<unknown>;
+export declare const workspaceCommands: readonly Command[];
+export {};
+//# sourceMappingURL=workspace.d.ts.map

package/dist/cli/cloud/commands/workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.d.ts","sourceRoot":"","sources":["../../../../src/cli/cloud/commands/workspace.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAcH,KAAK,OAAO,EACZ,KAAK,cAAc,EACtB,MAAM,eAAe,CAAC;AAEvB,QAAA,MAAM,UAAU;;;;;;iBAOd,CAAC;AAEH,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC,OAAO,UAAU,CAAC,CAAC;AAIxD,iEAAiE;AACjE,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,CAAwC,CAAC;AAEvF,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAOzF;AAED;;;GAGG;AACH,wBAAsB,WAAW,CAC7B,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAClF,GAAG,EAAE,OAAO,GACb,OAAO,CAAC;IAAE,OAAO,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC,CAQ7B;AAgBD,8EAA8E;AAC9E,wBAAsB,kBAAkB,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC,CAE1F;AAoFD,0FAA0F;AAC1F,wBAAsB,iBAAiB,CACnC,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACf,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAyCD,6FAA6F;AAC7F,wBAAsB,kBAAkB,CACpC,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACf,OAAO,CAAC,OAAO,CAAC,CAMlB;AAED,6EAA6E;AAC7E,wBAAsB,iBAAiB,CACnC,OAAO,EAAE,cAAc,EACvB,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,OAAO,GACf,OAAO,CAAC,OAAO,CAAC,CAalB;AAoHD,eAAO,MAAM,iBAAiB,EAAE,SAAS,OAAO,EAA4B,CAAC"}

package/dist/cli/cloud/commands/workspace.js

@@ -0,0 +1,279 @@
+// `workspace`: the tools an agent uses in your Dexto workspace over MCP, called as you.
+import { z } from 'zod';
+import { argument, BODY_OPTIONS, CommandFailure, flag, isJsonObject, MissingScopeFailure, readJsonBody, requireConsent, rerunWith, signInCommand, stringOption, UsageError, YES_OPTION, } from '../command.js';
+const ToolSchema = z.object({
+    /** `dexto/app`, `dexto/app_kind` and `dexto/level` say which app provides the tool and how it asks. */
+    _meta: z.record(z.string(), z.unknown()).optional(),
+    description: z.string().optional(),
+    inputSchema: z.unknown(),
+    name: z.string(),
+    title: z.string().optional(),
+});
+const ToolListSchema = z.object({ tools: z.array(ToolSchema) });
+/** The levels at which a call asks the person before it runs. */
+export const ASKING_LEVELS = new Set(['act', 'approve', 'money']);
+/** A tool's level for one call: its action's own level, where the action decides it. */
+export function toolCallLevel(tool, input) {
+    const levels = tool._meta?.['dexto/action_levels'];
+    const actionLevel = isJsonObject(levels) && typeof input.action === 'string' ? levels[input.action] : undefined;
+    if (typeof actionLevel === 'string')
+        return actionLevel;
+    const level = tool._meta?.['dexto/level'];
+    return typeof level === 'string' ? level : 'act';
+}
+/**
+ * Agrees to a call that asks first, by `--yes` or at the terminal, and returns what to add to its
+ * input: `confirm: true` where the tool takes it, the server's sign that the person agreed.
+ */
+export async function agreeToCall(context, call, yes) {
+    if (!ASKING_LEVELS.has(call.level))
+        return {};
+    await requireConsent(context, yes, `"${call.title}" asks before it runs (level ${call.level}).`);
+    return takesConfirm(call.schema) ? { confirm: true } : {};
+}
+function takesConfirm(schema) {
+    if (!isJsonObject(schema))
+        return false;
+    const variants = [
+        schema,
+        ...[schema.anyOf, schema.oneOf].flatMap((each) => (Array.isArray(each) ? each : [])),
+    ];
+    return variants.some((variant) => isJsonObject(variant) &&
+        isJsonObject(variant.properties) &&
+        'confirm' in variant.properties);
+}
+/** Every workspace tool the sign-in can call, as the Dexto MCP lists them. */
+export async function listWorkspaceTools(context) {
+    return ToolListSchema.parse(await callMcp(context, 'tools/list', {})).tools;
+}
+const ToolResultSchema = z.object({
+    content: z
+        .array(z.object({ text: z.string().optional(), type: z.string() }).passthrough())
+        .default([]),
+    isError: z.boolean().optional(),
+    structuredContent: z.unknown().optional(),
+});
+const tools = {
+    options: {
+        search: {
+            description: 'Only tools whose name or description has this text.',
+            type: 'string',
+        },
+    },
+    path: ['workspace', 'tools'],
+    summary: 'List the workspace tools your sign-in can call.',
+    async run(context, input) {
+        const search = stringOption(input, 'search')?.toLowerCase();
+        const listed = (await listWorkspaceTools(context)).filter((tool) => search === undefined ||
+            tool.name.toLowerCase().includes(search) ||
+            (tool.description ?? '').toLowerCase().includes(search));
+        context.output.list({ data: listed }, [
+            { header: 'name', value: (tool) => tool.name },
+            {
+                header: 'title',
+                value: (tool) => tool.title ?? tool.description ?? '',
+            },
+        ]);
+    },
+};
+const describe = {
+    arguments: '<tool>',
+    path: ['workspace', 'describe'],
+    summary: "Show a workspace tool's description and the input it takes.",
+    async run(context, input) {
+        const name = argument(input, 0, 'tool');
+        const tool = (await listWorkspaceTools(context)).find((each) => each.name === name);
+        if (tool === undefined)
+            throw new UsageError(`No workspace tool ${name}. List them with dexto workspace tools.`);
+        if (context.output.json)
+            return context.output.record(tool);
+        context.runtime.writeOutput(`${tool.title ?? tool.name}\n\n${tool.description ?? ''}\n\nInput:\n${JSON.stringify(tool.inputSchema, null, 2)}\n`);
+    },
+};
+const call = {
+    arguments: '<tool>',
+    options: { ...BODY_OPTIONS, ...YES_OPTION },
+    path: ['workspace', 'call'],
+    summary: 'Call a workspace tool with its input as JSON, such as: dexto workspace call dexto_search --data \'{"query":"invoices"}\'',
+    async run(context, input) {
+        const body = await readJsonBody(context, input);
+        if (body !== null && !isJsonObject(body))
+            throw new UsageError("A tool's input must be a JSON object.");
+        const name = argument(input, 0, 'tool');
+        const tool = (await listWorkspaceTools(context)).find((each) => each.name === name);
+        // A tool the sign-in isn't listed can't run anyway: the server refuses it and says why.
+        const agreed = tool === undefined
+            ? {}
+            : await agreeToCall(context, {
+                level: toolCallLevel(tool, body ?? {}),
+                schema: tool.inputSchema,
+                title: tool.title ?? tool.name,
+            }, flag(input, 'yes'));
+        return await callWorkspaceTool(context, name, { ...body, ...agreed });
+    },
+};
+/** Calls a workspace tool and prints its result; a tool's own error fails the command. */
+export async function callWorkspaceTool(context, name, input) {
+    const result = ToolResultSchema.parse(await callMcp(context, 'tools/call', { arguments: input, name }));
+    if (result.isError === true)
+        throw toolFailure(context, result);
+    if (context.output.json)
+        context.output.record(toolValue(result));
+    else {
+        const text = result.content
+            .map((part) => part.text)
+            .filter((part) => part !== undefined);
+        context.runtime.writeOutput(text.length > 0
+            ? `${text.join('\n')}\n`
+            : `${JSON.stringify(result.structuredContent ?? result.content, null, 2)}\n`);
+    }
+    return 0;
+}
+/** A tool result's value: its structured content, else its text as JSON, else the text itself. */
+function toolValue(result) {
+    if (result.structuredContent !== undefined)
+        return result.structuredContent;
+    const text = result.content
+        .map((part) => part.text)
+        .filter((part) => part !== undefined)
+        .join('\n');
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return { text };
+    }
+}
+/** A tool's own error as a failure: not found, a permission to grant, or a failed call. */
+function toolFailure(context, result) {
+    const value = toolValue(result);
+    const error = isJsonObject(value) && isJsonObject(value.error) ? value.error : null;
+    const status = isJsonObject(value) ? (value.status ?? error?.code) : undefined;
+    const text = result.content
+        .map((part) => part.text)
+        .filter((part) => part !== undefined)
+        .join('\n');
+    const message = (isJsonObject(value) && typeof value.message === 'string' && value.message) ||
+        (typeof error?.message === 'string' && error.message) ||
+        text ||
+        'The tool reported an error.';
+    if (status === 'not_found')
+        return new CommandFailure('not_found', message, null);
+    const scopes = isJsonObject(value) && Array.isArray(value.requiredScopes) ? value.requiredScopes : [];
+    if (status === 'consent_required' && scopes.length > 0)
+        return new MissingScopeFailure(context, scopes.map(String).join(','), message);
+    return new CommandFailure('failed', message, null);
+}
+/** Calls a workspace tool for its value, without printing it; the tool's own error fails. */
+export async function queryWorkspaceTool(context, name, input) {
+    const result = ToolResultSchema.parse(await callMcp(context, 'tools/call', { arguments: input, name }));
+    if (result.isError === true)
+        throw toolFailure(context, result);
+    return toolValue(result);
+}
+/** Calls a workspace tool for its structured result, without printing it. */
+export async function readWorkspaceTool(context, name, input) {
+    const result = ToolResultSchema.parse(await callMcp(context, 'tools/call', { arguments: input, name }));
+    if (result.isError === true)
+        return null;
+    if (result.structuredContent !== undefined)
+        return result.structuredContent;
+    const text = result.content.find((part) => part.text !== undefined)?.text;
+    if (text === undefined)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+let nextRequestId = 1;
+/**
+ * One JSON-RPC request to the Dexto MCP with the person's token. It takes only a person's sign-in:
+ * the workspace acts as a person, never as a project key.
+ */
+async function callMcp(context, method, params) {
+    const connection = await context.connection();
+    if (connection.kind !== 'oauth')
+        throw new CommandFailure('needs_sign_in', "Workspace tools act as you, so an API key can't use them. Sign in as yourself.", signInCommand(context, null));
+    const response = await context.runtime.fetch(connection.login.resource, {
+        body: JSON.stringify({
+            id: nextRequestId++,
+            jsonrpc: '2.0',
+            method,
+            params,
+        }),
+        headers: {
+            accept: 'application/json, text/event-stream',
+            authorization: `Bearer ${connection.token}`,
+            'content-type': 'application/json',
+        },
+        method: 'POST',
+        signal: context.runtime.signal,
+    });
+    if (response.status === 401 || response.status === 403)
+        throw new CommandFailure('needs_sign_in', "Your sign-in can't reach the workspace. Sign in again to grant it.", signInCommand(context, null));
+    const text = await response.text();
+    if (!response.ok)
+        throw new Error(`The Dexto MCP answered HTTP ${response.status}.`);
+    const message = parseJsonRpc(response.headers.get('content-type')?.includes('text/event-stream') === true
+        ? lastEventData(text)
+        : text);
+    if (message.error !== undefined)
+        throw refusalFailure(context, message.error);
+    return message.result;
+}
+/**
+ * A refusal as a failure, by the kind, scope and level its `data` names. Servers that send no
+ * `data` say it only in the message, so that is read too.
+ */
+function refusalFailure(context, error) {
+    const data = RefusalDataSchema.safeParse(error.data).data ?? {};
+    // `scopes` when any one of several would do: asking for the first is enough.
+    const scope = data.scope ?? data.scopes?.[0] ?? MISSING_SCOPE.exec(error.message)?.[1];
+    if (scope !== undefined)
+        return new MissingScopeFailure(context, scope, data.scopes !== undefined && data.scopes.length > 1
+            ? `This needs one of the ${data.scopes.join(', ')} permissions, which your sign-in doesn't have.`
+            : `This needs the ${scope} permission, which your sign-in doesn't have.`);
+    if (data.kind === 'needs_confirmation')
+        return new CommandFailure('needs_confirmation', error.message, rerunWith(context, '--yes'));
+    if (data.kind === 'not_found' ||
+        (data.kind === undefined && /\bnot found\b/iu.test(error.message)))
+        return new CommandFailure('not_found', error.message, null);
+    if (data.kind === 'forbidden' || (data.kind === undefined && error.code === -32003))
+        return new CommandFailure('needs_permission', error.message, null);
+    if (data.kind === 'invalid_arguments' ||
+        data.kind === 'unprocessable' ||
+        (data.kind === undefined && error.code === -32602))
+        return new CommandFailure('invalid_input', error.message, null);
+    return new CommandFailure('failed', error.message, null);
+}
+/** How the Dexto MCP refuses a tool the token's grant doesn't cover. */
+const MISSING_SCOPE = /missing required scope: ([\w:.-]+?)\.?$/u;
+const RefusalDataSchema = z.object({
+    kind: z.string().optional(),
+    level: z.string().optional(),
+    scope: z.string().optional(),
+    scopes: z.array(z.string()).optional(),
+});
+const JsonRpcResponseSchema = z.object({
+    error: z
+        .object({ code: z.number(), data: z.unknown().optional(), message: z.string() })
+        .optional(),
+    result: z.unknown().optional(),
+});
+function parseJsonRpc(text) {
+    return JsonRpcResponseSchema.parse(JSON.parse(text));
+}
+function lastEventData(stream) {
+    const data = stream
+        .split('\n')
+        .filter((line) => line.startsWith('data:'))
+        .map((line) => line.slice(5).trim());
+    const last = data.at(-1);
+    if (last === undefined)
+        throw new Error('The Dexto MCP sent no reply.');
+    return last;
+}
+export const workspaceCommands = [tools, describe, call];

package/dist/cli/cloud/connection.d.ts

@@ -0,0 +1,33 @@
+import { dextoAccounts } from '@dexto/agent-management';
+/** The global `--api-key`, `--api-base-url`, `--profile` and `--project` values, when given. */
+export interface ConnectionOverrides {
+    readonly apiBaseUrl: string | null;
+    readonly apiKey: string | null;
+    readonly cloudProject: string | null;
+    readonly profile: string | null;
+}
+export type Connection = {
+    readonly apiBaseUrl: string;
+    /** The Cloud project a person's token acts in: --project, DEXTO_CLOUD_PROJECT or the saved one. */
+    readonly cloudProject: string | null;
+    /** The profile whose sign-in this is, or that --profile or DEXTO_PROFILE named. */
+    readonly profile: string;
+    readonly source: dextoAccounts.CredentialSource;
+} & ({
+    readonly kind: 'api_key';
+    readonly token: string;
+} | {
+    readonly kind: 'oauth';
+    readonly token: string;
+    readonly login: dextoAccounts.OAuthLogin;
+});
+export interface ResolveConnectionInput {
+    /** ~/.dexto/accounts */
+    readonly dir: string;
+    readonly environment: Readonly<Record<string, string | undefined>>;
+    readonly overrides: ConnectionOverrides;
+    readonly refresh: (login: dextoAccounts.OAuthLogin) => Promise<dextoAccounts.OAuthLogin>;
+}
+/** --api-key, then DEXTO_API_KEY, then the profile's sign-in, refreshed when due; null when none. */
+export declare function resolveConnection(input: ResolveConnectionInput): Promise<Connection | null>;
+//# sourceMappingURL=connection.d.ts.map

package/dist/cli/cloud/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../../src/cli/cloud/connection.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAIxD,gGAAgG;AAChG,MAAM,WAAW,mBAAmB;IAChC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,MAAM,UAAU,GAAG;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,mGAAmG;IACnG,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,gBAAgB,CAAC;CACnD,GAAG,CACE;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,UAAU,CAAA;CAAE,CACjG,CAAC;AAEF,MAAM,WAAW,sBAAsB;IACnC,wBAAwB;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,WAAW,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACnE,QAAQ,CAAC,SAAS,EAAE,mBAAmB,CAAC;IACxC,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,CAAC,UAAU,KAAK,OAAO,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;CAC5F;AAED,qGAAqG;AACrG,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,sBAAsB,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAgCjG"}

package/dist/cli/cloud/connection.js

@@ -0,0 +1,38 @@
+// How a cloud command reaches Dexto: the sign-in or key, the API origin and the Cloud project.
+import { dextoAccounts } from '@dexto/agent-management';
+const DEFAULT_API_BASE_URL = 'https://api.dexto.ai';
+/** --api-key, then DEXTO_API_KEY, then the profile's sign-in, refreshed when due; null when none. */
+export async function resolveConnection(input) {
+    const credential = await dextoAccounts.resolveCredential({
+        dir: input.dir,
+        apiKey: input.overrides.apiKey,
+        profile: input.overrides.profile,
+        environment: input.environment,
+        refresh: input.refresh,
+    });
+    if (credential === null)
+        return null;
+    const saved = credential.kind === 'oauth'
+        ? credential.login
+        : credential.source === 'login'
+            ? await dextoAccounts.readLogin(input.dir, credential.profile)
+            : null;
+    const apiBaseUrl = (input.overrides.apiBaseUrl ??
+        nonEmpty(input.environment.DEXTO_API_BASE_URL) ??
+        saved?.apiBaseUrl ??
+        DEFAULT_API_BASE_URL).replace(/\/+$/u, '');
+    const named = input.overrides.cloudProject ?? nonEmpty(input.environment.DEXTO_CLOUD_PROJECT);
+    const base = { apiBaseUrl, profile: credential.profile, source: credential.source };
+    return credential.kind === 'oauth'
+        ? {
+            ...base,
+            kind: 'oauth',
+            token: credential.token,
+            login: credential.login,
+            cloudProject: named ?? credential.login.cloudProject?.id ?? null,
+        }
+        : { ...base, kind: 'api_key', token: credential.token, cloudProject: named };
+}
+function nonEmpty(value) {
+    return value === undefined || value.length === 0 ? null : value;
+}

package/dist/cli/cloud/events.d.ts

@@ -0,0 +1,63 @@
+import type { CommandContext } from './command.js';
+interface RunUsage {
+    readonly credits: number;
+    readonly input_tokens: number;
+    readonly output_tokens: number;
+}
+/** The events a run sends that the CLI shows; the API documents each. */
+export type AgentEvent = {
+    readonly type: 'run.started';
+    readonly run_id: string;
+} | {
+    readonly type: 'message.delta';
+    readonly run_id: string;
+    readonly text: string;
+} | {
+    readonly type: 'message.completed';
+    readonly run_id: string;
+    readonly text: string;
+} | {
+    readonly type: 'tool.started';
+    readonly run_id: string;
+    readonly name: string;
+    readonly arguments: unknown;
+} | {
+    readonly type: 'tool.completed';
+    readonly run_id: string;
+    readonly name: string;
+    readonly status: string;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    } | null;
+} | {
+    readonly type: 'approval.requested';
+    readonly run_id: string;
+    readonly approval_id: string;
+    readonly tool_name: string | null;
+    readonly input: unknown;
+} | {
+    readonly type: 'approval.resolved';
+    readonly run_id: string;
+} | {
+    readonly type: 'run.completed';
+    readonly run_id: string;
+    readonly stop_reason: string;
+    readonly usage: RunUsage;
+} | {
+    readonly type: 'run.failed';
+    readonly run_id: string;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+} | {
+    readonly type: 'run.cancelled';
+    readonly run_id: string;
+};
+/** Parses one SSE block; comments, blocks without data and unknown events are skipped. */
+export declare function parseEventBlock(block: string): AgentEvent | null;
+/** The session's events until the stream closes or `signal` aborts. */
+export declare function sessionEvents(context: CommandContext, agentId: string, sessionId: string, signal: AbortSignal): AsyncGenerator<AgentEvent>;
+export {};
+//# sourceMappingURL=events.d.ts.map

package/dist/cli/cloud/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/cli/cloud/events.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAGnD,UAAU,QAAQ;IACd,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAClC;AAED,yEAAyE;AACzE,MAAM,MAAM,UAAU,GAChB;IAAE,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAClF;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACtF;IACI,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC/B,GACD;IACI,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAC9E,GACD;IACI,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CAC3B,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC/D;IACI,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;CAC5B,GACD;IACI,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACvE,GACD;IAAE,QAAQ,CAAC,IAAI,EAAE,eAAe,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AA4BlE,0FAA0F;AAC1F,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI,CAYhE;AAED,uEAAuE;AACvE,wBAAuB,aAAa,CAChC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,WAAW,GACpB,cAAc,CAAC,UAAU,CAAC,CA6B5B"}

package/dist/cli/cloud/events.js

@@ -0,0 +1,72 @@
+// A session's events, as `GET /v1/agents/{agent_id}/sessions/{session_id}/events` streams them.
+import { sendV1, v1Failure } from './v1.js';
+const TYPES = new Set([
+    'run.started',
+    'message.delta',
+    'message.completed',
+    'tool.started',
+    'tool.completed',
+    'approval.requested',
+    'approval.resolved',
+    'run.completed',
+    'run.failed',
+    'run.cancelled',
+]);
+/** A known event; the server's own contract carries the rest of its fields. */
+function isAgentEvent(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'type' in value &&
+        typeof value.type === 'string' &&
+        TYPES.has(value.type) &&
+        'run_id' in value &&
+        typeof value.run_id === 'string');
+}
+/** Parses one SSE block; comments, blocks without data and unknown events are skipped. */
+export function parseEventBlock(block) {
+    const data = [];
+    for (const line of block.split('\n'))
+        if (line.startsWith('data:'))
+            data.push(line.slice(5).trimStart());
+    if (data.length === 0)
+        return null;
+    let value;
+    try {
+        value = JSON.parse(data.join('\n'));
+    }
+    catch {
+        return null;
+    }
+    return isAgentEvent(value) ? value : null;
+}
+/** The session's events until the stream closes or `signal` aborts. */
+export async function* sessionEvents(context, agentId, sessionId, signal) {
+    const response = await sendV1(context, 'GET', `/v1/agents/${encodeURIComponent(agentId)}/sessions/${encodeURIComponent(sessionId)}/events`, { body: null, headers: { accept: 'text/event-stream' } }, signal);
+    if (!response.ok)
+        throw v1Failure(context, response.status, await response.text());
+    if (response.body === null)
+        return;
+    const reader = response.body.pipeThrough(new globalThis.TextDecoderStream()).getReader();
+    let buffer = '';
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += value;
+            const blocks = buffer.split('\n\n');
+            buffer = blocks.pop() ?? '';
+            for (const block of blocks) {
+                const event = parseEventBlock(block);
+                if (event !== null)
+                    yield event;
+            }
+        }
+        const last = parseEventBlock(buffer);
+        if (last !== null)
+            yield last;
+    }
+    finally {
+        await reader.cancel().catch(() => undefined);
+    }
+}

package/dist/cli/cloud/host.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from './command.js';
+import { type SignInFor } from './commands/account.js';
+import type { CloudHost, Group } from './run.js';
+/** Help's areas: what `dexto cloud` builds with. */
+export declare const CLOUD_GROUPS: Readonly<Record<string, readonly Group[]>>;
+/** Every ported cloud command; `dir` is where sign-ins are saved. */
+export declare function cloudCommands(dir: string, signIn: SignInFor): readonly Command[];
+export declare function nodeCloudHost(signal: AbortSignal): CloudHost;
+//# sourceMappingURL=host.d.ts.map

package/dist/cli/cloud/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../../src/cli/cloud/host.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAoBxE,OAAO,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC;AAIjD,oDAAoD;AACpD,eAAO,MAAM,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC,CAgBnE,CAAC;AAEF,qEAAqE;AACrE,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,GAAG,SAAS,OAAO,EAAE,CAuBhF;AAED,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,CAyC5D"}

package/dist/cli/cloud/host.js

@@ -0,0 +1,105 @@
+// The cloud commands on this machine: the sign-in under ~/.dexto/accounts and Dexto's public API.
+import { dextoGateway } from '@dexto/agent-management';
+import { getDextoGlobalPath } from '@dexto/core';
+import { accountCommands } from './commands/account.js';
+import { agentCommands } from './commands/agents.js';
+import { apiCommands } from './commands/api.js';
+import { chatCommands } from './commands/chats.js';
+import { automationCommands } from './commands/automations.js';
+import { dataDeletionCommands } from './commands/data-deletions.js';
+import { deployCommands } from './commands/deploys.js';
+import { driveCommands } from './commands/drive.js';
+import { findCommands } from './commands/find.js';
+import { profileCommands } from './commands/profile.js';
+import { publishCommands } from './commands/publish.js';
+import { skillCommands } from './commands/skills.js';
+import { fileCommands } from './commands/files.js';
+import { modelCommands } from './commands/models.js';
+import { projectCommands, projectsUse } from './commands/projects.js';
+import { sandboxCommands } from './commands/sandboxes.js';
+import { secretCommands } from './commands/secrets.js';
+import { webCommands } from './commands/web.js';
+import { workspaceCommands } from './commands/workspace.js';
+import { resolveConnection } from './connection.js';
+import { nodeCloudRuntime } from './runtime.js';
+import { DEXTO_CREDITS_URL } from '../auth/constants.js';
+/** Help's areas: what `dexto cloud` builds with. */
+export const CLOUD_GROUPS = {
+    cloud: [
+        { name: 'projects', summary: 'List, create and choose Cloud projects' },
+        { name: 'agents', summary: 'Define agents, chat with them, read their sessions and runs' },
+        { name: 'automations', summary: 'Run agents on a schedule or a webhook' },
+        { name: 'files', summary: "Upload, download, share and delete the project's files" },
+        { name: 'sandboxes', summary: 'Create sandboxes, run commands in them and move files' },
+        { name: 'secrets', summary: 'Credentials agents use without seeing them' },
+        { name: 'sites', summary: 'Deploy, list and delete Sites, packed with their own packer' },
+        { name: 'functions', summary: 'Deploy and list Functions, packed with their own packer' },
+        { name: 'models', summary: 'Run text and media models, and see media runs' },
+        { name: 'search', summary: 'Search the web' },
+        { name: 'fetch', summary: 'Read web pages' },
+        { name: 'data-deletions', summary: "Delete an end user's or agent's data" },
+        { name: 'api', summary: 'Call any /v1 operation directly' },
+    ],
+};
+/** Every ported cloud command; `dir` is where sign-ins are saved. */
+export function cloudCommands(dir, signIn) {
+    return [
+        ...accountCommands(signIn, DEXTO_CREDITS_URL),
+        ...projectCommands,
+        projectsUse(dir),
+        ...agentCommands,
+        ...automationCommands,
+        ...fileCommands,
+        ...sandboxCommands,
+        ...secretCommands,
+        ...deployCommands,
+        ...modelCommands,
+        ...webCommands,
+        ...dataDeletionCommands,
+        ...apiCommands,
+        ...workspaceCommands,
+        ...driveCommands,
+        ...findCommands,
+        ...profileCommands,
+        ...publishCommands,
+        ...skillCommands,
+        ...chatCommands,
+    ];
+}
+export function nodeCloudHost(signal) {
+    const dir = getDextoGlobalPath('accounts');
+    const runtime = nodeCloudRuntime(signal);
+    const gateway = dextoGateway.defaultDextoGatewayOptions();
+    const signIn = async (io) => (await import('../commands/auth/sign-in-context.js')).nodeSignInContext(io);
+    return {
+        commands: cloudCommands(dir, signIn),
+        signIn,
+        groups: CLOUD_GROUPS,
+        runtime,
+        resolveConnection: (overrides) => resolveConnection({
+            dir,
+            environment: runtime.environment,
+            overrides,
+            refresh: gateway.refresh,
+        }),
+        signInForScope: async (overrides, scope) => {
+            const { login } = await import('../commands/auth/sign-in-commands.js');
+            // The sign-in's own words go to stderr: stdout is the command that runs again.
+            const toStderr = (text) => runtime.writeError(`${text}\n`);
+            await login(await signIn({
+                result: (_value, text) => toStderr(text),
+                note: toStderr,
+                confirm: async () => false,
+                signal,
+            }), {
+                profile: overrides.profile,
+                org: null,
+                device: false,
+                browser: true,
+                scopes: [scope],
+                apiKey: null,
+            });
+            return true;
+        },
+    };
+}