@agent-api/sdk 1.1.0 → 1.1.2

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog — @agent-api/sdk
 
+## 1.1.2
+
+### Added
+
+- Added a model-facing `local_workspace` driver/tool primitive for local workspace operations.
+- Added approval-aware dispatch for mutating local workspace actions.
+
+### Changed
+
+- Replaced fragmented local workspace tool presentation with an action-based adapter over the low-level local APIs.
+
+## 1.1.1
+
+### Added
+
+- Browser/device login helpers for CLI and desktop integrations: `client.auth.startDeviceAuth()`, `client.auth.pollDeviceAuth()`, and `client.auth.waitForDeviceAuth()`.
+- Convenience methods on `AgentAPI`: `startDeviceAuth()`, `pollDeviceAuth()`, and `waitForDeviceAuth()`.
+- `DeviceAuthFlowError` for expired, consumed, or timed-out device login flows.
+
 ## 1.1.0
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 Production JavaScript/TypeScript SDK for the Managed Agent API.
 
-**Published on npm:** [`@agent-api/sdk`](https://www.npmjs.com/package/@agent-api/sdk) (v1.0.8)
+**Published on npm:** [`@agent-api/sdk`](https://www.npmjs.com/package/@agent-api/sdk) (v1.1.2)
 
 ## Install
 
@@ -46,7 +46,7 @@ src/
   errors.ts           # Typed error hierarchy + retry helpers
   pagination.ts       # Cursor pagination utilities
   streaming.ts        # SSE parser
-  resources/          # responses, models, presets, tools, volumes, skills
+  resources/          # auth, responses, models, presets, tools, volumes, skills
   types/              # Request/response TypeScript types
   internal/http.ts    # Retries, timeouts, User-Agent
 ```
@@ -61,6 +61,25 @@ src/
 | `client.tools` | `list` |
 | `client.volumes` | `list`, `create`, `retrieve`, `update`, `delete`, `listEntries`, `searchEntries`, `readFile`, `writeFile`, `deletePath`, `reconcileUsage`, `createDirectory`, `downloadArchive`, `summarize`, `readLines`, `patchLines`, `grep` |
 | `client.skills` | `list`, `create`, `discover`, `focus`, `createDev`, `updateFile`, `retrieve`, `update`, `archive`, `delete`, `diff`, `acceptDev`, `discardDev`, `exportArchive`, `importArchive`, `pushDirectory`, `pullDirectory`, `listFiles`, `readFile`, `writeFile`, `deleteFile` |
+| `client.auth` | `startDeviceAuth`, `pollDeviceAuth`, `waitForDeviceAuth` |
+
+## Browser Device Login
+
+CLI and desktop apps can use browser login without handling user passwords or static API keys.
+
+```typescript
+const challenge = await client.auth.startDeviceAuth({ client_name: "Agent CLI" });
+console.log(`Open ${challenge.verification_uri_complete}`);
+
+const session = await client.auth.waitForDeviceAuth({
+  device_code: challenge.device_code,
+  interval_seconds: challenge.interval_seconds,
+});
+
+console.log(session.access_token);
+```
+
+The SDK returns URLs and polling helpers only. Opening the browser belongs to the CLI, Electron, Tauri, or native host app.
 
 ## Durable Volumes
 

package/dist/client.d.ts

@@ -1,3 +1,4 @@
+import { AuthResource } from "./resources/auth.js";
 import { ModelsResource } from "./resources/models.js";
 import { PresetsResource } from "./resources/presets.js";
 import { ResponsesResource } from "./resources/responses.js";
@@ -23,7 +24,11 @@ export declare class AgentAPI {
     readonly tools: ToolsResource;
     readonly volumes: VolumesResource;
     readonly skills: SkillsResource;
+    readonly auth: AuthResource;
     private readonly http;
     constructor(options?: ClientOptions);
+    startDeviceAuth: (...args: Parameters<AuthResource["startDeviceAuth"]>) => Promise<import("./index.js").DeviceAuthStart>;
+    pollDeviceAuth: (...args: Parameters<AuthResource["pollDeviceAuth"]>) => Promise<import("./index.js").DeviceAuthPollResult>;
+    waitForDeviceAuth: (...args: Parameters<AuthResource["waitForDeviceAuth"]>) => Promise<import("./index.js").ApprovedDeviceAuth>;
 }
 export { VERSION };

package/dist/client.js

@@ -1,6 +1,7 @@
 import { APIConnectionError } from "./errors.js";
 import { readEnv } from "./internal/env.js";
 import { HTTPClient } from "./internal/http.js";
+import { AuthResource } from "./resources/auth.js";
 import { ModelsResource } from "./resources/models.js";
 import { PresetsResource } from "./resources/presets.js";
 import { ResponsesResource } from "./resources/responses.js";
@@ -25,6 +26,7 @@ export class AgentAPI {
     tools;
     volumes;
     skills;
+    auth;
     http;
     constructor(options = {}) {
         this.apiKey = options.apiKey ?? readEnv("AGENT_API_KEY");
@@ -53,6 +55,10 @@ export class AgentAPI {
         this.tools = new ToolsResource(this.http);
         this.volumes = new VolumesResource(this.http);
         this.skills = new SkillsResource(this.http);
+        this.auth = new AuthResource(this.http);
     }
+    startDeviceAuth = (...args) => this.auth.startDeviceAuth(...args);
+    pollDeviceAuth = (...args) => this.auth.pollDeviceAuth(...args);
+    waitForDeviceAuth = (...args) => this.auth.waitForDeviceAuth(...args);
 }
 export { VERSION };

package/dist/index.d.ts

@@ -5,5 +5,8 @@ export { APIError, APIConnectionError, APIStatusError, AuthenticationError, BadR
 export * from "./types/index.js";
 export { functionCallOutputInput, pendingFunctionCalls, runLocalFunctionHandlers, } from "./local-functions.js";
 export type { LocalFunctionHandler, LocalFunctionHandlers } from "./local-functions.js";
+export { LocalWorkspaceDriver, createLocalWorkspaceToolRegistry, localWorkspaceToolDefinition, localWorkspaceToolInstructions, } from "./local/tools.js";
+export type { LocalWorkspaceAction, LocalWorkspaceAccessMode, LocalWorkspaceToolRegistry, LocalWorkspaceToolRegistryOptions, } from "./local/tools.js";
 export { localSkillFromDirectory, pendingLocalSkillCalls, runLocalSkillHandlers } from "./local-skills.js";
 export type { LocalSkillDirectoryOptions } from "./local-skills.js";
+export { AuthResource, DeviceAuthFlowError } from "./resources/auth.js";

package/dist/index.js

@@ -3,4 +3,6 @@ export { Page, collectPage } from "./pagination.js";
 export { APIError, APIConnectionError, APIStatusError, AuthenticationError, BadRequestError, InternalServerError, NotFoundError, PermissionDeniedError, RateLimitError, isRetryableStatus, parseResponseError, } from "./errors.js";
 export * from "./types/index.js";
 export { functionCallOutputInput, pendingFunctionCalls, runLocalFunctionHandlers, } from "./local-functions.js";
+export { LocalWorkspaceDriver, createLocalWorkspaceToolRegistry, localWorkspaceToolDefinition, localWorkspaceToolInstructions, } from "./local/tools.js";
 export { localSkillFromDirectory, pendingLocalSkillCalls, runLocalSkillHandlers } from "./local-skills.js";
+export { AuthResource, DeviceAuthFlowError } from "./resources/auth.js";

package/dist/local/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./core.js";
 export * from "./context.js";
+export * from "./tools.js";

package/dist/local/index.js

@@ -1,2 +1,3 @@
 export * from "./core.js";
 export * from "./context.js";
+export * from "./tools.js";

package/dist/local/tools.d.ts

@@ -0,0 +1,34 @@
+import type { FunctionTool } from "../types/tools.js";
+import type { LocalWorkspace } from "./core.js";
+export type LocalWorkspaceAccessMode = "approval" | "full";
+export type LocalWorkspaceAction = "summarize" | "list" | "search" | "grep" | "read" | "read_lines" | "context" | "snapshot" | "classify_path" | "preview_edits" | "apply_edits" | "write" | "mkdir" | "delete";
+export interface LocalWorkspaceToolRegistryOptions {
+    accessMode?: LocalWorkspaceAccessMode;
+    toolName?: string;
+}
+export interface LocalWorkspaceToolRegistry {
+    readonly workspace: LocalWorkspace;
+    readonly accessMode: LocalWorkspaceAccessMode;
+    readonly toolName: string;
+    definitions(): FunctionTool[];
+    handlers(): Record<string, (args: Record<string, unknown>) => Promise<Record<string, unknown>>>;
+    execute(name: string, args: Record<string, unknown>): Promise<Record<string, unknown>>;
+    requiresApproval(name: string, args?: Record<string, unknown>): boolean;
+}
+export interface LocalWorkspaceDriverOptions {
+    accessMode?: LocalWorkspaceAccessMode;
+}
+export declare class LocalWorkspaceDriver {
+    readonly workspace: LocalWorkspace;
+    readonly accessMode: LocalWorkspaceAccessMode;
+    constructor(workspace: LocalWorkspace, options?: LocalWorkspaceDriverOptions);
+    dispatch(args: Record<string, unknown>): Promise<Record<string, unknown>>;
+    requiresApproval(args: Record<string, unknown>): boolean;
+    private dispatchApplyEdits;
+    private dispatchWrite;
+    private dispatchMkdir;
+    private dispatchDelete;
+}
+export declare function createLocalWorkspaceToolRegistry(workspace: LocalWorkspace, options?: LocalWorkspaceToolRegistryOptions): LocalWorkspaceToolRegistry;
+export declare function localWorkspaceToolDefinition(name?: string): FunctionTool;
+export declare function localWorkspaceToolInstructions(): string;

package/dist/local/tools.js

@@ -0,0 +1,373 @@
+import { createLocalContextPackage } from "./context.js";
+export class LocalWorkspaceDriver {
+    workspace;
+    accessMode;
+    constructor(workspace, options = {}) {
+        this.workspace = workspace;
+        this.accessMode = options.accessMode ?? "approval";
+    }
+    async dispatch(args) {
+        const action = workspaceAction(args);
+        switch (action) {
+            case "summarize":
+                return localToolResult(action, localSummaryResult(await this.workspace.summarize(summaryArgs(args))));
+            case "list":
+                return localToolResult(action, await this.workspace.listEntries(optionalStringArg(args, "path") ?? ".", listArgs(args)));
+            case "search":
+                return localToolResult(action, await this.workspace.searchEntries(searchEntriesArgs(args)));
+            case "grep":
+                return localToolResult(action, await this.workspace.grep(grepArgs(args)));
+            case "read":
+                return localToolResult(action, await this.workspace.readFile(stringArg(args, "path"), readFileArgs(args)));
+            case "read_lines":
+                return localToolResult(action, await this.workspace.readLines(stringArg(args, "path"), readLinesArgs(args)));
+            case "context":
+                return localToolResult(action, await createLocalContextPackage(this.workspace, contextPackageArgs(args)));
+            case "snapshot":
+                return localToolResult(action, await this.workspace.snapshot(snapshotArgs(args)));
+            case "classify_path":
+                return localToolResult(action, this.workspace.classifyPath(stringArg(args, "path")));
+            case "preview_edits":
+                return localToolResult(action, await this.workspace.previewEdits(editsArg(args)));
+            case "apply_edits":
+                return await this.dispatchApplyEdits(args);
+            case "write":
+                return await this.dispatchWrite(args);
+            case "mkdir":
+                return await this.dispatchMkdir(args);
+            case "delete":
+                return await this.dispatchDelete(args);
+            default:
+                throw new Error(`unsupported local_workspace action: ${action}`);
+        }
+    }
+    requiresApproval(args) {
+        if (this.accessMode === "full") {
+            return false;
+        }
+        return mutatingLocalWorkspaceActions.has(workspaceAction(args));
+    }
+    async dispatchApplyEdits(args) {
+        const edits = editsArg(args);
+        if (this.accessMode !== "full") {
+            return approvalRequired("apply_edits", args, await this.workspace.previewEdits(edits));
+        }
+        return localToolResult("apply_edits", await this.workspace.applyEdits(edits));
+    }
+    async dispatchWrite(args) {
+        if (this.accessMode !== "full") {
+            return approvalRequired("write", args);
+        }
+        return localToolResult("write", await this.workspace.writeText(stringArg(args, "path"), stringArg(args, "content")));
+    }
+    async dispatchMkdir(args) {
+        if (this.accessMode !== "full") {
+            return approvalRequired("mkdir", args);
+        }
+        return localToolResult("mkdir", await this.workspace.createDirectory(stringArg(args, "path")));
+    }
+    async dispatchDelete(args) {
+        if (this.accessMode !== "full") {
+            return approvalRequired("delete", args);
+        }
+        return localToolResult("delete", await this.workspace.deletePath(stringArg(args, "path")));
+    }
+}
+export function createLocalWorkspaceToolRegistry(workspace, options = {}) {
+    const toolName = options.toolName ?? "local_workspace";
+    const driver = new LocalWorkspaceDriver(workspace, { accessMode: options.accessMode });
+    const definition = localWorkspaceToolDefinition(toolName);
+    return {
+        workspace,
+        accessMode: driver.accessMode,
+        toolName,
+        definitions: () => [{ ...definition }],
+        handlers: () => ({ [toolName]: (args) => driver.dispatch(args) }),
+        execute: async (name, args) => {
+            if (name !== toolName) {
+                throw new Error(`unknown local workspace tool: ${name}`);
+            }
+            return await driver.dispatch(args);
+        },
+        requiresApproval: (name, args = {}) => name === toolName && driver.requiresApproval(args),
+    };
+}
+export function localWorkspaceToolDefinition(name = "local_workspace") {
+    return {
+        type: "function",
+        name,
+        description: localWorkspaceToolDescription,
+        parameters: localWorkspaceToolParameters(),
+        strict: false,
+    };
+}
+export function localWorkspaceToolInstructions() {
+    return localWorkspaceToolDescription;
+}
+const localWorkspaceActions = [
+    "summarize",
+    "list",
+    "search",
+    "grep",
+    "read",
+    "read_lines",
+    "context",
+    "snapshot",
+    "classify_path",
+    "preview_edits",
+    "apply_edits",
+    "write",
+    "mkdir",
+    "delete",
+];
+const mutatingLocalWorkspaceActions = new Set([
+    "apply_edits",
+    "write",
+    "mkdir",
+    "delete",
+]);
+const localWorkspaceToolDescription = [
+    "Inspect and modify the selected local workspace through one model-facing primitive.",
+    "Use action=list/search/grep/summarize/context to discover files, read/read_lines for file content, preview_edits before edits, and apply_edits/write/mkdir/delete only when mutation is intended.",
+    "In approval mode, mutating actions return requires_approval with a safe preview instead of changing files. In full mode, mutating actions execute immediately.",
+    "Paths are relative to the selected local workspace; never use absolute paths.",
+].join(" ");
+function localWorkspaceToolParameters() {
+    return objectSchema({
+        action: {
+            type: "string",
+            enum: localWorkspaceActions,
+            description: "Workspace operation. Prefer summarize/list/search/grep before reading or editing. Prefer read_lines and apply_edits for source changes.",
+        },
+        path: stringSchema("Relative path. File path for read/write/delete/edit actions; directory base for list/search/grep/summarize/context/snapshot."),
+        query: stringSchema("Path/name query for search, or optional context query."),
+        pattern: stringSchema("Literal text pattern for grep."),
+        content: stringSchema("Text content for write."),
+        start_line: integerSchema("1-based start line for read_lines and edit entries."),
+        end_line: integerSchema("1-based inclusive end line; omit or 0 for EOF when supported."),
+        replacement: stringSchema("Replacement text for simple single edit flows."),
+        edits: {
+            type: "array",
+            minItems: 1,
+            description: "Line edits for preview_edits/apply_edits.",
+            items: objectSchema({
+                path: requiredStringSchema("Relative file path."),
+                start_line: requiredIntegerSchema("1-based start line."),
+                end_line: integerSchema("1-based inclusive end line."),
+                replacement: stringSchema("Replacement text. Empty string deletes the line range."),
+                expected_sha256: stringSchema("Optional expected SHA-256 for conflict detection."),
+            }, ["path", "start_line"]),
+        },
+        options: objectSchema({
+            recursive: booleanSchema("List recursively."),
+            include_directories: booleanSchema("Include directories in list results."),
+            max_depth: integerSchema("Maximum recursive list depth."),
+            limit: integerSchema("Maximum entries or matches."),
+            max_files: integerSchema("Maximum files to scan or package."),
+            max_bytes: integerSchema("Maximum total bytes to read/package."),
+            max_bytes_per_file: integerSchema("Maximum bytes per file."),
+            max_previews: integerSchema("Maximum summary previews."),
+            include_content: booleanSchema("Include file contents in context packages."),
+            include_summary: booleanSchema("Include workspace summary in context packages."),
+            include_search: booleanSchema("Include grep results in context packages when query is set."),
+            include_secrets: booleanSchema("Include likely secret file contents in context packages."),
+            hash: booleanSchema("Include SHA-256 hashes in snapshots."),
+        }),
+    }, ["action"]);
+}
+function workspaceAction(args) {
+    const value = stringArg(args, "action").trim().toLowerCase();
+    if (!localWorkspaceActions.includes(value)) {
+        throw new Error(`unsupported local_workspace action: ${value}`);
+    }
+    return value;
+}
+function summaryArgs(args) {
+    return {
+        path: optionalStringArg(args, "path"),
+        maxFiles: optionalNumberArg(args, "maxFiles", "max_files"),
+        maxPreviews: optionalNumberArg(args, "maxPreviews", "max_previews"),
+    };
+}
+function grepArgs(args) {
+    return {
+        pattern: stringArg(args, "pattern"),
+        path: optionalStringArg(args, "path"),
+        limit: optionalNumberArg(args, "limit"),
+        maxFiles: optionalNumberArg(args, "maxFiles", "max_files"),
+    };
+}
+function listArgs(args) {
+    return {
+        recursive: optionalBooleanArg(args, "recursive"),
+        includeDirectories: optionalBooleanArg(args, "includeDirectories", "include_directories"),
+        maxDepth: optionalNumberArg(args, "maxDepth", "max_depth"),
+    };
+}
+function searchEntriesArgs(args) {
+    return {
+        query: stringArg(args, "query"),
+        path: optionalStringArg(args, "path"),
+        limit: optionalNumberArg(args, "limit"),
+    };
+}
+function readFileArgs(args) {
+    return {
+        maxBytes: optionalNumberArg(args, "maxBytes", "max_bytes"),
+    };
+}
+function readLinesArgs(args) {
+    return {
+        startLine: numberArg(args, "startLine", "start_line"),
+        endLine: optionalNumberArg(args, "endLine", "end_line"),
+        maxBytes: optionalNumberArg(args, "maxBytes", "max_bytes"),
+    };
+}
+function snapshotArgs(args) {
+    return {
+        path: optionalStringArg(args, "path"),
+        hash: optionalBooleanArg(args, "hash"),
+        maxBytesPerFile: optionalNumberArg(args, "maxBytesPerFile", "max_bytes_per_file"),
+    };
+}
+function contextPackageArgs(args) {
+    return {
+        path: optionalStringArg(args, "path"),
+        query: optionalStringArg(args, "query"),
+        maxFiles: optionalNumberArg(args, "maxFiles", "max_files"),
+        maxBytes: optionalNumberArg(args, "maxBytes", "max_bytes"),
+        maxBytesPerFile: optionalNumberArg(args, "maxBytesPerFile", "max_bytes_per_file"),
+        includeContent: optionalBooleanArg(args, "includeContent", "include_content"),
+        includeSummary: optionalBooleanArg(args, "includeSummary", "include_summary"),
+        includeSearch: optionalBooleanArg(args, "includeSearch", "include_search"),
+        includeSecrets: optionalBooleanArg(args, "includeSecrets", "include_secrets"),
+    };
+}
+function editsArg(args) {
+    const edits = args.edits;
+    if (Array.isArray(edits) && edits.length > 0) {
+        return edits.map((edit) => {
+            if (!edit || typeof edit !== "object") {
+                throw new Error("each edit must be an object");
+            }
+            return editArg(edit);
+        });
+    }
+    if (typeof args.path === "string" && typeof (args.startLine ?? args.start_line) === "number") {
+        return [editArg(args)];
+    }
+    throw new Error("edits must be a non-empty array");
+}
+function editArg(record) {
+    return {
+        path: stringArg(record, "path"),
+        startLine: numberArg(record, "startLine", "start_line"),
+        endLine: optionalNumberArg(record, "endLine", "end_line"),
+        replacement: typeof record.replacement === "string" ? record.replacement : "",
+        expectedSha256: optionalStringArg(record, "expectedSha256", "expected_sha256"),
+    };
+}
+function localSummaryResult(summary) {
+    return summary;
+}
+function localToolResult(action, value) {
+    const result = value;
+    if (result && typeof result === "object" && !Array.isArray(result)) {
+        return { ok: true, action, ...result };
+    }
+    return { ok: true, action, result };
+}
+function stringArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error(`${key} must be a non-empty string`);
+    }
+    return value;
+}
+function optionalStringArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (value == null || value === "")
+        return undefined;
+    if (typeof value !== "string") {
+        throw new Error(`${key} must be a string`);
+    }
+    return value;
+}
+function numberArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${key} must be a number`);
+    }
+    return Math.trunc(value);
+}
+function optionalNumberArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (value == null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`${key} must be a number`);
+    }
+    return Math.trunc(value);
+}
+function optionalBooleanArg(args, key, alternateKey) {
+    const direct = args[key] ?? (alternateKey ? args[alternateKey] : undefined);
+    const fromOptions = args.options && typeof args.options === "object"
+        ? args.options[key] ?? (alternateKey ? args.options[alternateKey] : undefined)
+        : undefined;
+    const value = direct ?? fromOptions;
+    if (value == null)
+        return undefined;
+    if (typeof value !== "boolean") {
+        throw new Error(`${key} must be a boolean`);
+    }
+    return value;
+}
+function approvalRequired(action, args, preview) {
+    return {
+        ok: false,
+        action,
+        requires_approval: true,
+        arguments: args,
+        preview,
+        message: `local_workspace action ${action} requires approval`,
+    };
+}
+function objectSchema(properties, required = []) {
+    return {
+        type: "object",
+        properties,
+        required,
+        additionalProperties: false,
+    };
+}
+function stringSchema(description) {
+    return { type: "string", description };
+}
+function requiredStringSchema(description) {
+    return stringSchema(description);
+}
+function integerSchema(description) {
+    return { type: "integer", description };
+}
+function booleanSchema(description) {
+    return { type: "boolean", description };
+}
+function requiredIntegerSchema(description) {
+    return integerSchema(description);
+}

package/dist/resources/auth.d.ts

@@ -0,0 +1,14 @@
+import type { HTTPClient } from "../internal/http.js";
+import type { ApprovedDeviceAuth, DeviceAuthPollResult, DeviceAuthStart, PollDeviceAuthParams, StartDeviceAuthParams, WaitForDeviceAuthParams } from "../types/auth.js";
+import type { RequestOptions } from "../types/common.js";
+export declare class AuthResource {
+    private readonly http;
+    constructor(http: HTTPClient);
+    startDeviceAuth(params?: StartDeviceAuthParams, options?: RequestOptions): Promise<DeviceAuthStart>;
+    pollDeviceAuth(params: PollDeviceAuthParams, options?: RequestOptions): Promise<DeviceAuthPollResult>;
+    waitForDeviceAuth(params: WaitForDeviceAuthParams, options?: RequestOptions): Promise<ApprovedDeviceAuth>;
+}
+export declare class DeviceAuthFlowError extends Error {
+    readonly result?: DeviceAuthPollResult;
+    constructor(message: string, result?: DeviceAuthPollResult);
+}

package/dist/resources/auth.js

@@ -0,0 +1,87 @@
+const defaultDevicePollIntervalSeconds = 5;
+export class AuthResource {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    startDeviceAuth(params = {}, options = {}) {
+        return this.http.request("POST", "/v1/auth/device/start", params, options);
+    }
+    pollDeviceAuth(params, options = {}) {
+        requireDeviceCode(params.device_code);
+        return this.http.request("POST", "/v1/auth/device/poll", params, options);
+    }
+    async waitForDeviceAuth(params, options = {}) {
+        requireDeviceCode(params.device_code);
+        const startedAt = Date.now();
+        for (;;) {
+            throwIfAborted(params.signal);
+            const result = await this.pollDeviceAuth({ device_code: params.device_code }, options);
+            params.on_poll?.(result);
+            if (result.status === "approved" && result.access_token && result.refresh_token) {
+                return result;
+            }
+            if (result.status === "expired" || result.status === "consumed") {
+                throw new DeviceAuthFlowError(result.message || `Device auth ${result.status}`, result);
+            }
+            const timeoutMs = effectiveTimeoutMs(params, result);
+            if (timeoutMs !== undefined && Date.now() - startedAt >= timeoutMs) {
+                throw new DeviceAuthFlowError("Device auth timed out", result);
+            }
+            await sleep(pollDelayMs(params, result), params.signal);
+        }
+    }
+}
+export class DeviceAuthFlowError extends Error {
+    result;
+    constructor(message, result) {
+        super(message);
+        this.name = "DeviceAuthFlowError";
+        this.result = result;
+        Object.setPrototypeOf(this, DeviceAuthFlowError.prototype);
+    }
+}
+function requireDeviceCode(deviceCode) {
+    if (!deviceCode || !deviceCode.trim()) {
+        throw new TypeError("device_code is required");
+    }
+}
+function pollDelayMs(params, result) {
+    const seconds = params.interval_seconds ?? result.interval_seconds ?? defaultDevicePollIntervalSeconds;
+    return Math.max(1, seconds) * 1000;
+}
+function effectiveTimeoutMs(params, result) {
+    if (params.timeout_ms !== undefined) {
+        return Math.max(0, params.timeout_ms);
+    }
+    const expiresAt = result.expires_at;
+    if (!expiresAt)
+        return undefined;
+    return Math.max(0, expiresAt * 1000 - Date.now());
+}
+function sleep(ms, signal) {
+    if (!signal) {
+        return new Promise((resolve) => setTimeout(resolve, ms));
+    }
+    throwIfAborted(signal);
+    return new Promise((resolve, reject) => {
+        const timeout = setTimeout(cleanupResolve, ms);
+        signal.addEventListener("abort", cleanupReject, { once: true });
+        function cleanupResolve() {
+            signal?.removeEventListener("abort", cleanupReject);
+            resolve();
+        }
+        function cleanupReject() {
+            clearTimeout(timeout);
+            reject(abortError());
+        }
+    });
+}
+function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw abortError();
+    }
+}
+function abortError() {
+    return new DOMException("Device auth wait aborted", "AbortError");
+}

package/dist/types/auth.d.ts

@@ -0,0 +1,63 @@
+export type DeviceAuthStatus = "pending" | "approved" | "expired" | "consumed" | string;
+export interface DeviceAuthStart {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_at: number;
+    interval_seconds: number;
+}
+export interface AuthSession {
+    access_token: string;
+    refresh_token: string;
+    token_type?: string;
+    access_token_expires_at: number;
+    refresh_token_expires_at?: number;
+    user_id: string;
+    workspace_id: string;
+    workspace_name?: string;
+    workspace_role: string;
+    scopes: string[];
+}
+export interface DeviceAuthPollResult {
+    status: DeviceAuthStatus;
+    message?: string;
+    interval_seconds?: number;
+    expires_at?: number;
+    access_token?: string;
+    refresh_token?: string;
+    token_type?: string;
+    access_token_expires_at?: number;
+    refresh_token_expires_at?: number;
+    user_id?: string;
+    workspace_id?: string;
+    workspace_name?: string;
+    workspace_role?: string;
+    scopes?: string[];
+}
+export type ApprovedDeviceAuth = DeviceAuthPollResult & {
+    status: "approved";
+    access_token: string;
+    refresh_token: string;
+    access_token_expires_at: number;
+    user_id: string;
+    workspace_id: string;
+    workspace_role: string;
+    scopes: string[];
+};
+export interface StartDeviceAuthParams {
+    client_name?: string;
+}
+export interface PollDeviceAuthParams {
+    device_code: string;
+}
+export interface WaitForDeviceAuthParams extends PollDeviceAuthParams {
+    /** Polling interval in seconds. Defaults to the server interval or 5 seconds. */
+    interval_seconds?: number;
+    /** Overall wait timeout in milliseconds. Defaults to the challenge expiry when present. */
+    timeout_ms?: number;
+    /** Optional cancellation signal for CLI/Desktop integrations. */
+    signal?: AbortSignal;
+    /** Called after every poll response, including pending responses. */
+    on_poll?: (result: DeviceAuthPollResult) => void;
+}

package/dist/types/auth.js

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

package/dist/types/index.d.ts

@@ -6,3 +6,4 @@ export * from "./streaming.js";
 export * from "./catalog.js";
 export * from "./volumes.js";
 export * from "./skills.js";
+export * from "./auth.js";

package/dist/types/index.js

@@ -6,3 +6,4 @@ export * from "./streaming.js";
 export * from "./catalog.js";
 export * from "./volumes.js";
 export * from "./skills.js";
+export * from "./auth.js";

package/dist/types/responses.d.ts

@@ -2,10 +2,17 @@ import type { AgentCapabilityPreference, ErrorInfo, ModelRoutingMode, ModelRouti
 import type { ContentPart, Input, MemoryOptions, ReasoningConfig, ResponseFormat } from "./input.js";
 import type { LocalSkillDescriptor, SkillReference } from "./skills.js";
 import type { Tool } from "./tools.js";
+export interface CallerContext {
+    timezone?: string;
+    locale?: string;
+    locality?: string;
+    extra?: unknown;
+}
 export interface ResponseCreateParamsBase {
     input: Input;
     instructions?: string;
     language_preference?: string;
+    caller_context?: CallerContext;
     model?: string;
     models?: string[];
     model_routing?: ModelRoutingMode;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "1.1.0";
-export declare const USER_AGENT = "@agent-api/sdk/1.1.0";
+export declare const VERSION = "1.1.2";
+export declare const USER_AGENT = "@agent-api/sdk/1.1.2";

package/dist/version.js

@@ -1,2 +1,2 @@
-export const VERSION = "1.1.0";
+export const VERSION = "1.1.2";
 export const USER_AGENT = `@agent-api/sdk/${VERSION}`;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-api/sdk",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Production JavaScript SDK for the Managed Agent API",
   "license": "MIT",
   "repository": {
@@ -46,7 +46,7 @@
     "build": "tsc -p tsconfig.json",
     "sync-version": "node scripts/sync-version.mjs",
     "prepack": "npm run sync-version && npm run build",
-    "test": "npm run sync-version && npm run build && node --test test/index.test.mjs test/local-function-integration.test.mjs test/local-runtime.test.mjs",
+    "test": "npm run sync-version && npm run build && node --test test/index.test.mjs test/local-function-integration.test.mjs test/local-runtime.test.mjs test/local-tools.test.mjs",
     "test:integration": "npm run sync-version && npm run build && node --test test/integration.test.mjs",
     "test:integration:local-functions": "npm run sync-version && npm run build && node --test test/local-function-integration.test.mjs",
     "check:routes": "node scripts/check-routes.mjs"