@kraki/tentacle 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kraki Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/adapters/base.d.ts

@@ -0,0 +1,107 @@
+/**
+ * Abstract base class for coding agent adapters.
+ *
+ * Each concrete adapter (Copilot, Claude Code, Codex, etc.) wraps
+ * an agent's SDK and normalises its events into Kraki protocol types.
+ *
+ * The tentacle runtime sets the `on*` callbacks before calling `start()`.
+ * The adapter fires them as the agent produces events.
+ */
+import type { ToolArgs } from '@kraki/protocol';
+import type { SessionContext } from '../session-manager.js';
+export interface SessionCreatedEvent {
+    sessionId: string;
+    agent: string;
+    model?: string;
+}
+export interface MessageEvent {
+    content: string;
+}
+export interface MessageDeltaEvent {
+    content: string;
+}
+export interface PermissionRequestEvent {
+    id: string;
+    toolArgs: ToolArgs;
+    description: string;
+}
+export interface QuestionRequestEvent {
+    id: string;
+    question: string;
+    choices?: string[];
+    allowFreeform: boolean;
+}
+export interface ToolStartEvent {
+    toolName: string;
+    args: Record<string, unknown>;
+    toolCallId?: string;
+}
+export interface ToolCompleteEvent {
+    toolName: string;
+    result: string;
+    toolCallId?: string;
+}
+export interface SessionEndedEvent {
+    reason: string;
+}
+export interface ErrorEvent {
+    message: string;
+}
+export interface CreateSessionConfig {
+    /** Agent-specific model identifier (e.g. "claude-opus-4.6-1m") */
+    model?: string;
+    /** Working directory for the session */
+    cwd?: string;
+    /** Caller-supplied session ID (adapter may ignore) */
+    sessionId?: string;
+}
+export interface SessionInfo {
+    id: string;
+    state: 'active' | 'idle' | 'ended';
+    model?: string;
+    cwd?: string;
+    summary?: string;
+}
+export type PermissionDecision = 'approve' | 'deny' | 'always_allow';
+export declare abstract class AgentAdapter {
+    onSessionCreated: ((event: SessionCreatedEvent) => void) | null;
+    onMessage: ((sessionId: string, event: MessageEvent) => void) | null;
+    onMessageDelta: ((sessionId: string, event: MessageDeltaEvent) => void) | null;
+    onPermissionRequest: ((sessionId: string, event: PermissionRequestEvent) => void) | null;
+    /** Called when a permission is auto-resolved (e.g. by "Always Allow" for same tool kind) */
+    onPermissionAutoResolved: ((sessionId: string, permissionId: string) => void) | null;
+    onQuestionRequest: ((sessionId: string, event: QuestionRequestEvent) => void) | null;
+    onToolStart: ((sessionId: string, event: ToolStartEvent) => void) | null;
+    onToolComplete: ((sessionId: string, event: ToolCompleteEvent) => void) | null;
+    onIdle: ((sessionId: string) => void) | null;
+    onError: ((sessionId: string, event: ErrorEvent) => void) | null;
+    onSessionEnded: ((sessionId: string, event: SessionEndedEvent) => void) | null;
+    /** Start the adapter (e.g. spawn CLI server). */
+    abstract start(): Promise<void>;
+    /** Stop the adapter and release all resources. */
+    abstract stop(): Promise<void>;
+    /** Create a new agent session. */
+    abstract createSession(config: CreateSessionConfig): Promise<{
+        sessionId: string;
+    }>;
+    /** Resume a previously created session with recovery context. */
+    abstract resumeSession(sessionId: string, context?: SessionContext): Promise<{
+        sessionId: string;
+    }>;
+    /** Send a user message to a session. */
+    abstract sendMessage(sessionId: string, text: string, attachments?: string[]): Promise<void>;
+    /** Respond to a pending permission request. */
+    abstract respondToPermission(sessionId: string, permissionId: string, decision: PermissionDecision): Promise<void>;
+    /** Respond to a pending agent question. */
+    abstract respondToQuestion(sessionId: string, questionId: string, answer: string, wasFreeform: boolean): Promise<void>;
+    /** Kill / disconnect a session. */
+    abstract killSession(sessionId: string): Promise<void>;
+    /** Abort the current turn (session stays alive). Override in concrete adapters. */
+    abortSession(_sessionId: string): Promise<void>;
+    /** List known sessions. */
+    abstract listSessions(): Promise<SessionInfo[]>;
+    /** List available models. Override in concrete adapters. */
+    listModels(): Promise<string[]>;
+    /** Set permission mode for a session. Override in concrete adapters. */
+    setSessionMode(_sessionId: string, _mode: 'ask' | 'auto'): void;
+}

package/dist/adapters/base.js

@@ -0,0 +1,32 @@
+/**
+ * Abstract base class for coding agent adapters.
+ *
+ * Each concrete adapter (Copilot, Claude Code, Codex, etc.) wraps
+ * an agent's SDK and normalises its events into Kraki protocol types.
+ *
+ * The tentacle runtime sets the `on*` callbacks before calling `start()`.
+ * The adapter fires them as the agent produces events.
+ */
+// ── The adapter interface ───────────────────────────────
+export class AgentAdapter {
+    // --- Callbacks (set by the tentacle runtime) ---
+    onSessionCreated = null;
+    onMessage = null;
+    onMessageDelta = null;
+    onPermissionRequest = null;
+    /** Called when a permission is auto-resolved (e.g. by "Always Allow" for same tool kind) */
+    onPermissionAutoResolved = null;
+    onQuestionRequest = null;
+    onToolStart = null;
+    onToolComplete = null;
+    onIdle = null;
+    onError = null;
+    onSessionEnded = null;
+    /** Abort the current turn (session stays alive). Override in concrete adapters. */
+    async abortSession(_sessionId) { }
+    /** List available models. Override in concrete adapters. */
+    async listModels() { return []; }
+    /** Set permission mode for a session. Override in concrete adapters. */
+    setSessionMode(_sessionId, _mode) { }
+}
+//# sourceMappingURL=base.js.map

package/dist/adapters/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/adapters/base.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA+EH,2DAA2D;AAE3D,MAAM,OAAgB,YAAY;IAChC,kDAAkD;IAElD,gBAAgB,GAAkD,IAAI,CAAC;IACvE,SAAS,GAA8D,IAAI,CAAC;IAC5E,cAAc,GAAmE,IAAI,CAAC;IACtF,mBAAmB,GAAwE,IAAI,CAAC;IAChG,4FAA4F;IAC5F,wBAAwB,GAA+D,IAAI,CAAC;IAC5F,iBAAiB,GAAsE,IAAI,CAAC;IAC5F,WAAW,GAAgE,IAAI,CAAC;IAChF,cAAc,GAAmE,IAAI,CAAC;IACtF,MAAM,GAAyC,IAAI,CAAC;IACpD,OAAO,GAA4D,IAAI,CAAC;IACxE,cAAc,GAAmE,IAAI,CAAC;IAuCtF,mFAAmF;IACnF,KAAK,CAAC,YAAY,CAAC,UAAkB,IAA0C,CAAC;IAKhF,4DAA4D;IAC5D,KAAK,CAAC,UAAU,KAAwB,OAAO,EAAE,CAAC,CAAC,CAAC;IAEpD,wEAAwE;IACxE,cAAc,CAAC,UAAkB,EAAE,KAAqB,IAAiC,CAAC;CAC3F"}

package/dist/adapters/copilot.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Copilot SDK adapter for Kraki.
+ *
+ * Wraps `@github/copilot-sdk` and normalises Copilot CLI events
+ * into the abstract `AgentAdapter` callback interface.
+ *
+ * Key responsibilities:
+ *  - Manage the CopilotClient lifecycle (start/stop the CLI server)
+ *  - Create/resume/kill sessions via the SDK
+ *  - Wire SDK streaming events → `on*` callbacks
+ *  - Implement the permission-request / question blocking pattern:
+ *    the SDK handler returns a Promise that resolves when the
+ *    remote user approves/denies/answers via the tentacle runtime.
+ */
+import { AgentAdapter, type CreateSessionConfig, type SessionInfo, type PermissionDecision } from './base.js';
+export declare function patchCopilotSdkSessionImport(currentUrl?: string): boolean;
+export declare function resolveCopilotSdkSessionPath(currentUrl?: string): string | null;
+export declare function installCopilotSdkImportCompatibility(currentUrl?: string): 'hook' | 'patch' | null;
+export declare class CopilotAdapter extends AgentAdapter {
+    private client;
+    private sessions;
+    private cliPath;
+    /** Per-session auto-approve sets (populated by "Always Allow" clicks) */
+    private sessionAllowSets;
+    /** Session permission mode: 'ask' (default) or 'auto' */
+    private sessionModes;
+    constructor(options?: {
+        cliPath?: string;
+    });
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    createSession(config: CreateSessionConfig): Promise<{
+        sessionId: string;
+    }>;
+    resumeSession(sessionId: string): Promise<{
+        sessionId: string;
+    }>;
+    sendMessage(sessionId: string, text: string, attachments?: string[]): Promise<void>;
+    respondToPermission(sessionId: string, permissionId: string, decision: PermissionDecision): Promise<void>;
+    respondToQuestion(sessionId: string, questionId: string, answer: string, wasFreeform: boolean): Promise<void>;
+    killSession(sessionId: string): Promise<void>;
+    abortSession(sessionId: string): Promise<void>;
+    listSessions(): Promise<SessionInfo[]>;
+    listModels(): Promise<string[]>;
+    /** Set permission mode for a session ('ask' or 'auto') */
+    setSessionMode(sessionId: string, mode: 'ask' | 'auto'): void;
+    /** Clean up session-scoped permission state */
+    private cleanupSessionPermissions;
+    private makeResumeConfig;
+    private resumeTrackedSession;
+    private handleUnavailableSession;
+    private wireEvents;
+    private makePermissionHandler;
+    private makeQuestionHandler;
+    private ensureClient;
+    private getSession;
+}