@snack-kit/porygon 0.2.0 → 0.3.0

package/dist/index.d.cts

@@ -128,7 +128,7 @@ interface AgentErrorMessage extends BaseAgentMessage {
  * 适配器能力声明
  */
 interface AdapterCapabilities {
-    features: Set<"streaming" | "session-resume" | "system-prompt" | "tool-restriction" | "mcp" | "subagents" | "worktree" | "budget-limit" | "serve-mode">;
+    features: Set<"streaming" | "session-resume" | "system-prompt" | "tool-restriction" | "mcp" | "subagents" | "worktree" | "budget-limit" | "serve-mode" | "interactive-session">;
     /**
      * 流式输出模式：
      * - 'delta': 后端原生产生增量 stream_chunk 事件（如 OpenCode）
@@ -209,6 +209,38 @@ interface InterceptorContext {
  */
 type InterceptorFn = (text: string, context: InterceptorContext) => string | boolean | undefined | Promise<string | boolean | undefined>;
 
+/**
+ * 便捷的多轮对话封装。
+ *
+ * 底层仍是 per-turn spawn + --resume，但对调用方透明：
+ * ```ts
+ * const session = porygon.session({ systemPrompt: '...' });
+ * for await (const msg of session.send('Hello')) { ... }
+ * for await (const msg of session.send('继续')) { ... }  // 自动 resume
+ * session.close();
+ * ```
+ */
+declare class InteractiveSession {
+    readonly initialSessionId: string;
+    private resolvedSessionId?;
+    private adapter;
+    private baseRequest;
+    private firstSent;
+    private closed;
+    constructor(initialSessionId: string, adapter: IAgentAdapter, baseRequest: Omit<PromptRequest, "prompt">);
+    /** 当前生效的 sessionId（首次 send 后反映 CLI 返回的真实 ID） */
+    get sessionId(): string;
+    /** 会话是否仍然活跃 */
+    get isActive(): boolean;
+    /**
+     * 发送一条消息，返回流式响应。
+     * 首次调用使用 initialSessionId，后续自动附加 resume。
+     */
+    send(prompt: string): AsyncGenerator<AgentMessage>;
+    /** 关闭会话（仅清理内部状态，无进程需要释放） */
+    close(): void;
+}
+
 /**
  * 健康检查结果（扁平化结构）
  */
@@ -270,6 +302,11 @@ declare class Porygon extends EventEmitter {
      * @returns 最终结果文本
      */
     run(request: PromptRequest): Promise<string>;
+    /**
+     * 创建交互式多轮对话会话。
+     * 自动管理 sessionId 和 resume，对调用方透明。
+     */
+    session(options?: Omit<PromptRequest, "prompt">): InteractiveSession;
     /**
      * 注册拦截器
      * @param direction 拦截方向
@@ -458,6 +495,8 @@ interface SpawnOptions {
     cwd?: string;
     env?: Record<string, string>;
     timeoutMs?: number;
+    /** 写入 stdin 后自动关闭的数据 */
+    stdinData?: string;
 }
 /**
  * 进程执行结果
@@ -681,6 +720,11 @@ declare class ClaudeAdapter extends AbstractAgentAdapter {
      * @param noProxy 不走代理的地址列表
      */
     private applyProxyEnv;
+    /**
+     * 构建通过 stdin 传递给 Claude CLI 的数据。
+     * 使用 stdin 而非 CLI 参数传递 prompt，避免超长参数导致的 403 错误。
+     */
+    private buildStdinData;
     private buildArgs;
 }
 
@@ -765,4 +809,4 @@ declare class OpenCodeAdapter extends AbstractAgentAdapter {
     private getConfigPath;
 }
 
-export { AbstractAgentAdapter, type AdapterCapabilities, AdapterIncompatibleError, AdapterNotAvailableError, AdapterNotFoundError, type AgentAssistantMessage, type AgentErrorMessage, AgentExecutionError, type AgentMessage, type AgentResultMessage, type AgentStreamChunkMessage, type AgentSystemMessage, AgentTimeoutError, type AgentToolUseMessage, type BackendConfig, ClaudeAdapter, type CompatibilityResult, ConfigValidationError, type GuardAction, type GuardOptions, type HealthCheckResult, type IAgentAdapter, type InterceptorContext, type InterceptorDirection, type InterceptorFn, InterceptorRejectedError, type McpServerConfig, type ModelInfo, OpenCodeAdapter, Porygon, type PorygonConfig, PorygonError, type PorygonEvents, type PromptRequest, type ProxyConfig, type SessionInfo, type SessionListOptions, SessionNotFoundError, createInputGuard, createOutputGuard, createPorygon };
+export { AbstractAgentAdapter, type AdapterCapabilities, AdapterIncompatibleError, AdapterNotAvailableError, AdapterNotFoundError, type AgentAssistantMessage, type AgentErrorMessage, AgentExecutionError, type AgentMessage, type AgentResultMessage, type AgentStreamChunkMessage, type AgentSystemMessage, AgentTimeoutError, type AgentToolUseMessage, type BackendConfig, ClaudeAdapter, type CompatibilityResult, ConfigValidationError, type GuardAction, type GuardOptions, type HealthCheckResult, type IAgentAdapter, InteractiveSession, type InterceptorContext, type InterceptorDirection, type InterceptorFn, InterceptorRejectedError, type McpServerConfig, type ModelInfo, OpenCodeAdapter, Porygon, type PorygonConfig, PorygonError, type PorygonEvents, type PromptRequest, type ProxyConfig, type SessionInfo, type SessionListOptions, SessionNotFoundError, createInputGuard, createOutputGuard, createPorygon };

package/dist/index.d.ts

@@ -128,7 +128,7 @@ interface AgentErrorMessage extends BaseAgentMessage {
  * 适配器能力声明
  */
 interface AdapterCapabilities {
-    features: Set<"streaming" | "session-resume" | "system-prompt" | "tool-restriction" | "mcp" | "subagents" | "worktree" | "budget-limit" | "serve-mode">;
+    features: Set<"streaming" | "session-resume" | "system-prompt" | "tool-restriction" | "mcp" | "subagents" | "worktree" | "budget-limit" | "serve-mode" | "interactive-session">;
     /**
      * 流式输出模式：
      * - 'delta': 后端原生产生增量 stream_chunk 事件（如 OpenCode）
@@ -209,6 +209,38 @@ interface InterceptorContext {
  */
 type InterceptorFn = (text: string, context: InterceptorContext) => string | boolean | undefined | Promise<string | boolean | undefined>;
 
+/**
+ * 便捷的多轮对话封装。
+ *
+ * 底层仍是 per-turn spawn + --resume，但对调用方透明：
+ * ```ts
+ * const session = porygon.session({ systemPrompt: '...' });
+ * for await (const msg of session.send('Hello')) { ... }
+ * for await (const msg of session.send('继续')) { ... }  // 自动 resume
+ * session.close();
+ * ```
+ */
+declare class InteractiveSession {
+    readonly initialSessionId: string;
+    private resolvedSessionId?;
+    private adapter;
+    private baseRequest;
+    private firstSent;
+    private closed;
+    constructor(initialSessionId: string, adapter: IAgentAdapter, baseRequest: Omit<PromptRequest, "prompt">);
+    /** 当前生效的 sessionId（首次 send 后反映 CLI 返回的真实 ID） */
+    get sessionId(): string;
+    /** 会话是否仍然活跃 */
+    get isActive(): boolean;
+    /**
+     * 发送一条消息，返回流式响应。
+     * 首次调用使用 initialSessionId，后续自动附加 resume。
+     */
+    send(prompt: string): AsyncGenerator<AgentMessage>;
+    /** 关闭会话（仅清理内部状态，无进程需要释放） */
+    close(): void;
+}
+
 /**
  * 健康检查结果（扁平化结构）
  */
@@ -270,6 +302,11 @@ declare class Porygon extends EventEmitter {
      * @returns 最终结果文本
      */
     run(request: PromptRequest): Promise<string>;
+    /**
+     * 创建交互式多轮对话会话。
+     * 自动管理 sessionId 和 resume，对调用方透明。
+     */
+    session(options?: Omit<PromptRequest, "prompt">): InteractiveSession;
     /**
      * 注册拦截器
      * @param direction 拦截方向
@@ -458,6 +495,8 @@ interface SpawnOptions {
     cwd?: string;
     env?: Record<string, string>;
     timeoutMs?: number;
+    /** 写入 stdin 后自动关闭的数据 */
+    stdinData?: string;
 }
 /**
  * 进程执行结果
@@ -681,6 +720,11 @@ declare class ClaudeAdapter extends AbstractAgentAdapter {
      * @param noProxy 不走代理的地址列表
      */
     private applyProxyEnv;
+    /**
+     * 构建通过 stdin 传递给 Claude CLI 的数据。
+     * 使用 stdin 而非 CLI 参数传递 prompt，避免超长参数导致的 403 错误。
+     */
+    private buildStdinData;
     private buildArgs;
 }
 
@@ -765,4 +809,4 @@ declare class OpenCodeAdapter extends AbstractAgentAdapter {
     private getConfigPath;
 }
 
-export { AbstractAgentAdapter, type AdapterCapabilities, AdapterIncompatibleError, AdapterNotAvailableError, AdapterNotFoundError, type AgentAssistantMessage, type AgentErrorMessage, AgentExecutionError, type AgentMessage, type AgentResultMessage, type AgentStreamChunkMessage, type AgentSystemMessage, AgentTimeoutError, type AgentToolUseMessage, type BackendConfig, ClaudeAdapter, type CompatibilityResult, ConfigValidationError, type GuardAction, type GuardOptions, type HealthCheckResult, type IAgentAdapter, type InterceptorContext, type InterceptorDirection, type InterceptorFn, InterceptorRejectedError, type McpServerConfig, type ModelInfo, OpenCodeAdapter, Porygon, type PorygonConfig, PorygonError, type PorygonEvents, type PromptRequest, type ProxyConfig, type SessionInfo, type SessionListOptions, SessionNotFoundError, createInputGuard, createOutputGuard, createPorygon };
+export { AbstractAgentAdapter, type AdapterCapabilities, AdapterIncompatibleError, AdapterNotAvailableError, AdapterNotFoundError, type AgentAssistantMessage, type AgentErrorMessage, AgentExecutionError, type AgentMessage, type AgentResultMessage, type AgentStreamChunkMessage, type AgentSystemMessage, AgentTimeoutError, type AgentToolUseMessage, type BackendConfig, ClaudeAdapter, type CompatibilityResult, ConfigValidationError, type GuardAction, type GuardOptions, type HealthCheckResult, type IAgentAdapter, InteractiveSession, type InterceptorContext, type InterceptorDirection, type InterceptorFn, InterceptorRejectedError, type McpServerConfig, type ModelInfo, OpenCodeAdapter, Porygon, type PorygonConfig, PorygonError, type PorygonEvents, type PromptRequest, type ProxyConfig, type SessionInfo, type SessionListOptions, SessionNotFoundError, createInputGuard, createOutputGuard, createPorygon };

package/dist/index.js

@@ -309,12 +309,18 @@ var EphemeralProcess = class {
       throw new Error("Process aborted before start");
     }
     this.aborted = false;
+    const useStdin = options.stdinData !== void 0;
     const child = spawn(options.command, options.args, {
       cwd: options.cwd,
       env: options.env ?? void 0,
-      stdio: ["ignore", "pipe", "pipe"]
+      stdio: [useStdin ? "pipe" : "ignore", "pipe", "pipe"]
     });
     this.childProcess = child;
+    if (useStdin && child.stdin) {
+      child.stdin.write(options.stdinData, () => {
+        child.stdin.end();
+      });
+    }
     let timeoutTimer;
     if (options.timeoutMs !== void 0 && options.timeoutMs > 0) {
       timeoutTimer = setTimeout(() => {
@@ -926,7 +932,8 @@ var ClaudeAdapter = class extends AbstractAgentAdapter {
         "tool-restriction",
         "mcp",
         "subagents",
-        "worktree"
+        "worktree",
+        "interactive-session"
       ]),
       streamingMode: "chunked",
       outputFormats: ["text", "json", "stream-json"],
@@ -959,12 +966,14 @@ var ClaudeAdapter = class extends AbstractAgentAdapter {
           if (v) cleanEnv[k] = v;
         }
       }
+      const stdinData = this.buildStdinData(request);
       const streamOptions = {
         command: this.cliCommand,
         args,
         ...cwd ? { cwd } : {},
         env: cleanEnv,
-        timeoutMs: request.timeoutMs
+        timeoutMs: request.timeoutMs,
+        stdinData
       };
       const cmdStr = [this.cliCommand, ...args.map((a) => /[\s"']/.test(a) ? JSON.stringify(a) : a)].join(" ");
       const debugCmd = cwd ? `cd ${JSON.stringify(cwd)} && ${cmdStr}` : cmdStr;
@@ -1097,10 +1106,16 @@ var ClaudeAdapter = class extends AbstractAgentAdapter {
       env["NO_PROXY"] = noProxy;
     }
   }
+  /**
+   * 构建通过 stdin 传递给 Claude CLI 的数据。
+   * 使用 stdin 而非 CLI 参数传递 prompt，避免超长参数导致的 403 错误。
+   */
+  buildStdinData(request) {
+    return request.prompt;
+  }
   buildArgs(request) {
     const args = [
-      "-p",
-      request.prompt,
+      "--print",
       "--output-format",
       "stream-json",
       "--verbose"
@@ -1712,6 +1727,54 @@ var OpenCodeAdapter = class extends AbstractAgentAdapter {
   }
 };
 
+// src/session/interactive-session.ts
+var InteractiveSession = class {
+  initialSessionId;
+  resolvedSessionId;
+  adapter;
+  baseRequest;
+  firstSent = false;
+  closed = false;
+  constructor(initialSessionId, adapter, baseRequest) {
+    this.initialSessionId = initialSessionId;
+    this.adapter = adapter;
+    this.baseRequest = baseRequest;
+  }
+  /** 当前生效的 sessionId（首次 send 后反映 CLI 返回的真实 ID） */
+  get sessionId() {
+    return this.resolvedSessionId ?? this.initialSessionId;
+  }
+  /** 会话是否仍然活跃 */
+  get isActive() {
+    return !this.closed;
+  }
+  /**
+   * 发送一条消息，返回流式响应。
+   * 首次调用使用 initialSessionId，后续自动附加 resume。
+   */
+  async *send(prompt) {
+    if (this.closed) {
+      throw new SessionNotFoundError(this.sessionId);
+    }
+    const request = {
+      ...this.baseRequest,
+      prompt,
+      ...this.firstSent ? { resume: this.sessionId } : {}
+    };
+    for await (const msg of this.adapter.query(request)) {
+      if (!this.firstSent && msg.sessionId) {
+        this.resolvedSessionId = msg.sessionId;
+      }
+      yield msg;
+    }
+    this.firstSent = true;
+  }
+  /** 关闭会话（仅清理内部状态，无进程需要释放） */
+  close() {
+    this.closed = true;
+  }
+};
+
 // src/porygon.ts
 var Porygon = class extends EventEmitter2 {
   config;
@@ -1811,6 +1874,21 @@ var Porygon = class extends EventEmitter2 {
     }
     return resultText;
   }
+  /**
+   * 创建交互式多轮对话会话。
+   * 自动管理 sessionId 和 resume，对调用方透明。
+   */
+  session(options) {
+    const backend = options?.backend ?? this.config.defaultBackend ?? "claude";
+    const adapter = this.getAdapter(backend);
+    const merged = this.mergeRequest({ ...options, prompt: "" }, backend);
+    const { prompt: _, ...baseRequest } = merged;
+    return new InteractiveSession(
+      crypto.randomUUID(),
+      adapter,
+      baseRequest
+    );
+  }
   /**
    * 注册拦截器
    * @param direction 拦截方向
@@ -2058,6 +2136,7 @@ export {
   AgentTimeoutError,
   ClaudeAdapter,
   ConfigValidationError,
+  InteractiveSession,
   InterceptorRejectedError,
   OpenCodeAdapter,
   Porygon,