@letta-ai/letta-code-sdk 0.0.1

package/dist/session.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Session
+ *
+ * Represents a conversation session with a Letta agent.
+ * Implements the V2 API pattern: send() / receive()
+ */
+import type { SessionOptions, SDKMessage, SDKInitMessage } from "./types.js";
+export declare class Session implements AsyncDisposable {
+    private options;
+    private transport;
+    private _agentId;
+    private _sessionId;
+    private _conversationId;
+    private initialized;
+    constructor(options?: SessionOptions & {
+        agentId?: string;
+    });
+    /**
+     * Initialize the session (called automatically on first send)
+     */
+    initialize(): Promise<SDKInitMessage>;
+    /**
+     * Send a message to the agent
+     */
+    send(message: string): Promise<void>;
+    /**
+     * Stream messages from the agent
+     */
+    stream(): AsyncGenerator<SDKMessage>;
+    /**
+     * Handle can_use_tool control request from CLI (Claude SDK compatible format)
+     */
+    private handleCanUseTool;
+    /**
+     * Abort the current operation (interrupt without closing the session)
+     */
+    abort(): Promise<void>;
+    /**
+     * Close the session
+     */
+    close(): void;
+    /**
+     * Get the agent ID (available after initialization)
+     */
+    get agentId(): string | null;
+    /**
+     * Get the session ID (available after initialization)
+     */
+    get sessionId(): string | null;
+    /**
+     * Get the conversation ID (available after initialization)
+     */
+    get conversationId(): string | null;
+    /**
+     * AsyncDisposable implementation for `await using`
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Transform wire message to SDK message
+     */
+    private transformMessage;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,cAAc,EACd,UAAU,EACV,cAAc,EASf,MAAM,YAAY,CAAC;AAGpB,qBAAa,OAAQ,YAAW,eAAe;IAQ3C,OAAO,CAAC,OAAO;IAPjB,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,eAAe,CAAuB;IAC9C,OAAO,CAAC,WAAW,CAAS;gBAGlB,OAAO,GAAE,cAAc,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO;IAO7D;;OAEG;IACG,UAAU,IAAI,OAAO,CAAC,cAAc,CAAC;IA2C3C;;OAEG;IACG,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW1C;;OAEG;IACI,MAAM,IAAI,cAAc,CAAC,UAAU,CAAC;IA0B3C;;OAEG;YACW,gBAAgB;IAiD9B;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ5B;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAED;;OAEG;IACH,IAAI,SAAS,IAAI,MAAM,GAAG,IAAI,CAE7B;IAED;;OAEG;IACH,IAAI,cAAc,IAAI,MAAM,GAAG,IAAI,CAElC;IAED;;OAEG;IACG,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC;IAI5C;;OAEG;IACH,OAAO,CAAC,gBAAgB;CAiIzB"}

package/dist/transport.d.ts

@@ -0,0 +1,43 @@
+/**
+ * SubprocessTransport
+ *
+ * Spawns the Letta Code CLI and communicates via stdin/stdout JSON streams.
+ */
+import type { SessionOptions, WireMessage } from "./types.js";
+export declare class SubprocessTransport {
+    private options;
+    private process;
+    private stdout;
+    private messageQueue;
+    private messageResolvers;
+    private closed;
+    private agentId?;
+    constructor(options?: SessionOptions & {
+        agentId?: string;
+    });
+    /**
+     * Start the CLI subprocess
+     */
+    connect(): Promise<void>;
+    /**
+     * Send a message to the CLI via stdin
+     */
+    write(data: object): Promise<void>;
+    /**
+     * Read the next message from the CLI
+     */
+    read(): Promise<WireMessage | null>;
+    /**
+     * Async iterator for messages
+     */
+    messages(): AsyncGenerator<WireMessage>;
+    /**
+     * Close the transport
+     */
+    close(): void;
+    get isClosed(): boolean;
+    private handleMessage;
+    private buildArgs;
+    private findCli;
+}
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9D,qBAAa,mBAAmB;IAS5B,OAAO,CAAC,OAAO;IARjB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,MAAM,CAA0B;IACxC,OAAO,CAAC,YAAY,CAAqB;IACzC,OAAO,CAAC,gBAAgB,CAAyC;IACjE,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAC,CAAS;gBAGf,OAAO,GAAE,cAAc,GAAG;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAO;IAG7D;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA2C9B;;OAEG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAOxC;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAiBzC;;OAEG;IACI,QAAQ,IAAI,cAAc,CAAC,WAAW,CAAC;IAQ9C;;OAEG;IACH,KAAK,IAAI,IAAI;IAeb,IAAI,QAAQ,IAAI,OAAO,CAEtB;IAED,OAAO,CAAC,aAAa;IAgBrB,OAAO,CAAC,SAAS;YAwJH,OAAO;CA0CtB"}

package/dist/types.d.ts

@@ -0,0 +1,172 @@
+/**
+ * SDK Types
+ *
+ * These are the public-facing types for SDK consumers.
+ * Protocol types are imported from @letta-ai/letta-code/protocol.
+ */
+export type { WireMessage, SystemInitMessage, MessageWire, ResultMessage, ErrorMessage, StreamEvent, ControlRequest, ControlResponse, CanUseToolControlRequest, CanUseToolResponse, CanUseToolResponseAllow, CanUseToolResponseDeny, SystemPromptPresetConfig, CreateBlock, } from "@letta-ai/letta-code/protocol";
+import type { CreateBlock } from "@letta-ai/letta-code/protocol";
+/**
+ * Available system prompt presets.
+ */
+export type SystemPromptPreset = "default" | "letta-claude" | "letta-codex" | "letta-gemini" | "claude" | "codex" | "gemini";
+/**
+ * System prompt preset configuration.
+ */
+export interface SystemPromptPresetConfigSDK {
+    type: "preset";
+    preset: SystemPromptPreset;
+    append?: string;
+}
+/**
+ * System prompt configuration - either a raw string or preset config.
+ */
+export type SystemPromptConfig = string | SystemPromptPresetConfigSDK;
+/**
+ * Reference to an existing shared block by ID.
+ */
+export interface BlockReference {
+    blockId: string;
+}
+/**
+ * Memory item - can be a preset name, custom block, or block reference.
+ */
+export type MemoryItem = string | CreateBlock | BlockReference;
+/**
+ * Default memory block preset names.
+ */
+export type MemoryPreset = "persona" | "human" | "project";
+/**
+ * Result of a canUseTool callback
+ */
+export interface PermissionResult {
+    allow: boolean;
+    reason?: string;
+}
+/**
+ * Callback for custom permission handling
+ */
+export type CanUseToolCallback = (toolName: string, toolInput: Record<string, unknown>) => Promise<PermissionResult> | PermissionResult;
+/**
+ * Options for creating a session
+ */
+export interface SessionOptions {
+    /** Model to use (e.g., "claude-sonnet-4-20250514") */
+    model?: string;
+    /** Resume a specific conversation by ID (derives agent automatically) */
+    conversationId?: string;
+    /** Create a new conversation for concurrent sessions (requires agentId) */
+    newConversation?: boolean;
+    /** Resume the last session (agent + conversation from previous run) */
+    continue?: boolean;
+    /** Use agent's default conversation (requires agentId) */
+    defaultConversation?: boolean;
+    /**
+     * System prompt configuration.
+     * - string: Use as the complete system prompt
+     * - { type: 'preset', preset, append? }: Use a preset with optional appended text
+     *
+     * Available presets: 'default', 'letta-claude', 'letta-codex', 'letta-gemini',
+     *                    'claude', 'codex', 'gemini'
+     */
+    systemPrompt?: SystemPromptConfig;
+    /**
+     * Memory block configuration. Each item can be:
+     * - string: Preset block name ("project", "persona", "human")
+     * - CreateBlock: Custom block definition
+     * - { blockId: string }: Reference to existing shared block
+     *
+     * If not specified, defaults to ["persona", "human", "project"].
+     * Core blocks (skills, loaded_skills) are always included automatically.
+     */
+    memory?: MemoryItem[];
+    /**
+     * Convenience: Set persona block value directly.
+     * Uses default block description/limit, just overrides the value.
+     * Error if persona not included in memory config.
+     */
+    persona?: string;
+    /**
+     * Convenience: Set human block value directly.
+     */
+    human?: string;
+    /**
+     * Convenience: Set project block value directly.
+     */
+    project?: string;
+    /** List of allowed tool names */
+    allowedTools?: string[];
+    /** Permission mode */
+    permissionMode?: PermissionMode;
+    /** Working directory */
+    cwd?: string;
+    /** Maximum conversation turns */
+    maxTurns?: number;
+    /** Custom permission callback - called when tool needs approval */
+    canUseTool?: CanUseToolCallback;
+}
+export type PermissionMode = "default" | "acceptEdits" | "bypassPermissions";
+/**
+ * SDK message types - clean wrappers around wire types
+ */
+export interface SDKInitMessage {
+    type: "init";
+    agentId: string;
+    sessionId: string;
+    conversationId: string;
+    model: string;
+    tools: string[];
+}
+export interface SDKAssistantMessage {
+    type: "assistant";
+    content: string;
+    uuid: string;
+}
+export interface SDKToolCallMessage {
+    type: "tool_call";
+    toolCallId: string;
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    uuid: string;
+}
+export interface SDKToolResultMessage {
+    type: "tool_result";
+    toolCallId: string;
+    content: string;
+    isError: boolean;
+    uuid: string;
+}
+export interface SDKReasoningMessage {
+    type: "reasoning";
+    content: string;
+    uuid: string;
+}
+export interface SDKResultMessage {
+    type: "result";
+    success: boolean;
+    result?: string;
+    error?: string;
+    durationMs: number;
+    totalCostUsd?: number;
+    conversationId: string | null;
+}
+export interface SDKStreamEventMessage {
+    type: "stream_event";
+    event: {
+        type: string;
+        index?: number;
+        delta?: {
+            type?: string;
+            text?: string;
+            reasoning?: string;
+        };
+        content_block?: {
+            type?: string;
+            text?: string;
+        };
+    };
+    uuid: string;
+}
+/** Union of all SDK message types */
+export type SDKMessage = SDKInitMessage | SDKAssistantMessage | SDKToolCallMessage | SDKToolResultMessage | SDKReasoningMessage | SDKResultMessage | SDKStreamEventMessage;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/validation.d.ts

@@ -0,0 +1,12 @@
+/**
+ * SDK Validation
+ *
+ * Validates SessionOptions before spawning the CLI.
+ */
+import type { SessionOptions } from "./types.js";
+/**
+ * Validate SessionOptions before spawning CLI.
+ * Throws an error if validation fails.
+ */
+export declare function validateSessionOptions(options: SessionOptions): void;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,YAAY,CAAC;AAe1E;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,CAsFpE"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@letta-ai/letta-code-sdk",
+  "version": "0.0.1",
+  "description": "SDK for programmatic control of Letta Code CLI",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "bun run build.ts",
+    "dev": "bun run build.ts --watch",
+    "check": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/letta-ai/letta-code-sdk"
+  },
+  "dependencies": {
+    "@letta-ai/letta-code": "latest"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0"
+}