qlogicagent 0.6.0 → 1.0.0

package/dist/types/protocol/notifications.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Centralized Notification Event Protocol — all JSON-RPC notification types
+ * that qlogicagent emits to external apps.
+ *
+ * This is the SINGLE SOURCE OF TRUTH for the agent's outbound event contract.
+ * Frontend, Electron, Hub, and test harness all consume these types.
+ *
+ * Reference: Codex app-server events, Claude Code streaming events,
+ *            DeerFlow LangGraph stream modes.
+ */
+import type { TokenUsage } from "../agent/types.js";
+import type { TodoItem } from "../contracts/todo.js";
+/** Embedded thread item for clients using the Thread protocol. */
+export interface NotificationThreadItem {
+    id: string;
+    type: string;
+    role: "user" | "assistant" | "system";
+    text?: string;
+    toolName?: string;
+    toolCallId?: string;
+    arguments?: string;
+    output?: string;
+    approved?: boolean;
+    strategy?: string;
+    createdAt: string;
+}
+/** Turn started — always emitted first. */
+export interface TurnStartNotification {
+    turnId: string;
+    /** Model being used for this turn (Codex parity). */
+    model?: string;
+    /** Provider id. */
+    provider?: string;
+}
+/** Streaming text chunk from the main agent. */
+export interface TurnDeltaNotification {
+    turnId: string;
+    text: string;
+    item?: NotificationThreadItem;
+}
+/** Turn completed successfully. */
+export interface TurnEndNotification {
+    turnId: string;
+    content: string;
+    usage?: TokenUsage;
+    model?: string;
+    provider?: string;
+    item?: NotificationThreadItem;
+}
+/** Turn failed. */
+export interface TurnErrorNotification {
+    turnId: string;
+    error: string;
+    code?: string;
+}
+/** Agent self-recovered from an error (retry, conversation repair, etc.). */
+export interface TurnRecoveryNotification {
+    turnId: string;
+    action: string;
+    detail?: string;
+    item?: NotificationThreadItem;
+}
+/** Tool invocation started — includes arguments for UI display. */
+export interface TurnToolCallNotification {
+    turnId: string;
+    callId: string;
+    name: string;
+    /** Serialized arguments JSON. Enables UI to display "searching for X", "reading file Y". */
+    arguments?: string;
+    item?: NotificationThreadItem;
+}
+/**
+ * Tool execution completed.
+ * Includes truncated output for "Used X sources" style panels.
+ */
+export interface TurnToolResultNotification {
+    turnId: string;
+    callId: string;
+    name: string;
+    ok: boolean;
+    error?: string;
+    /** Truncated tool output (max 2000 chars). Enables source preview panels. */
+    outputPreview?: string;
+    item?: NotificationThreadItem;
+}
+/** Tool execution blocked by permission system. */
+export interface TurnToolBlockedNotification {
+    turnId: string;
+    callId: string;
+    name: string;
+    reason: string;
+    item?: NotificationThreadItem;
+}
+/**
+ * Reasoning/thinking token stream — separate from main delta.
+ * Enables DeerFlow-style collapsible thinking blocks.
+ *
+ * For models that support extended thinking (Claude, DeepSeek-R1, o1),
+ * reasoning content is streamed via this event instead of turn.delta.
+ */
+export interface TurnReasoningDeltaNotification {
+    turnId: string;
+    text: string;
+}
+/** Plan/strategy update — rendered as DeerFlow Plan component. */
+export interface TurnPlanUpdateNotification {
+    turnId: string;
+    slug: string;
+    content: string;
+    item?: NotificationThreadItem;
+}
+/** Suggestion items — interactive quick-action buttons. */
+export interface TurnSuggestionsNotification {
+    turnId: string;
+    items: Array<{
+        text: string;
+        icon?: string;
+        action?: string;
+    }>;
+}
+/** Sub-agent (fork, skill, dream) started execution. */
+export interface TurnSubagentStartedNotification {
+    turnId: string;
+    subagentId: string;
+    agentType: string;
+    prompt?: string;
+}
+/** Sub-agent streaming text chunk. */
+export interface TurnSubagentDeltaNotification {
+    agentType: string;
+    subagentId?: string;
+    text: string;
+}
+/** Sub-agent completed execution. */
+export interface TurnSubagentEndedNotification {
+    turnId: string;
+    subagentId: string;
+    agentType: string;
+    ok: boolean;
+    /** Truncated result (max 2000 chars). */
+    outputPreview?: string;
+    error?: string;
+}
+export type MediaResultType = "image" | "tts" | "video";
+/** Structured media generation result — enables media preview cards. */
+export interface TurnMediaResultNotification {
+    turnId: string;
+    mediaType: MediaResultType;
+    /** Local file path or URL. */
+    url: string;
+    /** Model used for generation. */
+    model?: string;
+    /** Provider id. */
+    provider?: string;
+    /** Duration in seconds (for TTS/video). */
+    durationSeconds?: number;
+    /** Image dimensions. */
+    width?: number;
+    height?: number;
+    /** MIME type (e.g. "audio/mpeg", "image/png"). */
+    mimeType?: string;
+    /** Billing info. */
+    billingUnit?: string;
+    billingQuantity?: number;
+}
+/** Full todo list updated — enables DeerFlow-style todo panel sync. */
+export interface TurnTodosUpdatedNotification {
+    turnId?: string;
+    items: TodoItem[];
+    summary: {
+        total: number;
+        completed: number;
+        inProgress: number;
+        notStarted: number;
+    };
+}
+/** Infrastructure task state change (bash, agent fork, dream). */
+export interface TaskUpdatedNotification {
+    taskId: string;
+    type: string;
+    lifecycle: string;
+    label?: string;
+}
+/** Long-running command execution progress (shell, script). */
+export interface TurnExecProgressNotification {
+    output: string;
+    elapsedTimeSeconds: number;
+    totalLines: number;
+    totalBytes: number;
+}
+export type ArtifactType = "code" | "file" | "image" | "document" | "diagram" | "table";
+/** Structured artifact produced by the agent — enables Canvas-style rendering. */
+export interface TurnArtifactNotification {
+    turnId: string;
+    artifactId: string;
+    type: ArtifactType;
+    title: string;
+    /** File path (for file/code artifacts). */
+    filePath?: string;
+    /** Language id (for code artifacts). */
+    language?: string;
+    /** Content body (may be truncated for large artifacts). */
+    content?: string;
+    /** MIME type. */
+    mimeType?: string;
+}
+/** Agent requests user approval before executing a restricted tool. */
+export interface ToolApprovalRequestNotification {
+    approvalId: string;
+    callId: string;
+    toolName: string;
+    arguments: string;
+    message?: string;
+    suggestions?: string[];
+}
+/** Skill instruction directive. */
+export interface TurnSkillInstructionNotification {
+    turnId: string;
+    instruction: unknown;
+}
+/** Memory content changed (local md or QMemory). */
+export interface MemoryUpdatedNotification {
+    source: string;
+    /** Memory target (memory, user, etc.). */
+    target?: string;
+    /** Number of entries. */
+    entryCount?: number;
+    /** Human-readable summary of what changed. */
+    summary?: string;
+}
+/** Session metadata changed (title, model, etc.). */
+export interface SessionInfoNotification {
+    sessionId: string;
+    title?: string;
+    model?: string;
+    provider?: string;
+    cwd?: string;
+    turnCount?: number;
+}
+/** Permission rule saved/updated. */
+export interface PermissionRuleUpdatedNotification {
+    /** Tool name glob pattern. */
+    pattern: string;
+    /** New permission behavior (allow, deny, ask). */
+    behavior: string;
+}
+/** Team created, updated, or destroyed. */
+export interface TeamUpdatedNotification {
+    teamName: string;
+    action: "created" | "destroyed" | "member_joined" | "member_left";
+    members?: Array<{
+        agentName: string;
+        role: string;
+    }>;
+}
+export interface PongNotification {
+}
+/** Real-time token usage update (emitted after each LLM call within a turn). */
+export interface TurnUsageUpdateNotification {
+    turnId: string;
+    usage: TokenUsage;
+    model?: string;
+    /** Cumulative cost estimate for this session (USD). */
+    sessionCostUSD?: number;
+}
+export interface NotificationMethodMap {
+    "turn.start": TurnStartNotification;
+    "turn.delta": TurnDeltaNotification;
+    "turn.end": TurnEndNotification;
+    "turn.error": TurnErrorNotification;
+    "turn.recovery": TurnRecoveryNotification;
+    "turn.tool_call": TurnToolCallNotification;
+    "turn.tool_result": TurnToolResultNotification;
+    "turn.tool_blocked": TurnToolBlockedNotification;
+    "turn.reasoning_delta": TurnReasoningDeltaNotification;
+    "turn.plan_update": TurnPlanUpdateNotification;
+    "turn.suggestions": TurnSuggestionsNotification;
+    "turn.subagent_started": TurnSubagentStartedNotification;
+    "turn.subagent_delta": TurnSubagentDeltaNotification;
+    "turn.subagent_ended": TurnSubagentEndedNotification;
+    "turn.media_result": TurnMediaResultNotification;
+    "turn.todos_updated": TurnTodosUpdatedNotification;
+    "task.updated": TaskUpdatedNotification;
+    "turn.exec_progress": TurnExecProgressNotification;
+    "turn.artifact": TurnArtifactNotification;
+    "tool.approval.request": ToolApprovalRequestNotification;
+    "turn.skill_instruction": TurnSkillInstructionNotification;
+    "memory.updated": MemoryUpdatedNotification;
+    "session.info": SessionInfoNotification;
+    "permission.rule_updated": PermissionRuleUpdatedNotification;
+    "team.updated": TeamUpdatedNotification;
+    "turn.usage_update": TurnUsageUpdateNotification;
+    "pong": PongNotification;
+}
+/** All known notification method names. */
+export type NotificationMethod = keyof NotificationMethodMap;

package/dist/types/runtime/prompt/environment-context.d.ts

@@ -20,4 +20,4 @@ export type ShellType = "bash" | "powershell" | "zsh" | "cmd" | "fish" | "unknow
  * Create a system prompt section that provides environment context.
  * Memoized — computed once per session (environment doesn't change mid-session).
  */
-export declare function createEnvironmentContextSection(): SystemPromptSection;
+export declare function createEnvironmentContextSection(cwdOverride?: string): SystemPromptSection;

package/dist/types/runtime/session/index.d.ts

@@ -1,2 +1,2 @@
-export { SessionState, type SessionCostSnapshot } from "./session-state.js";
+export { SessionState, type SessionUsageSnapshot, type SessionCostSnapshot } from "./session-state.js";
 export { appendMessage, saveSessionState, loadSessionForResume, listSessions, deleteSession, pruneOldSessions, shouldGenerateTaskSummary, maybeGenerateTaskSummary, type SessionMetadata, type PersistedSession, type SessionListEntry, type TaskSummaryDeps, } from "./session-persistence.js";

package/dist/types/runtime/session/session-state.d.ts

@@ -21,18 +21,24 @@ export interface ModelUsage {
     outputTokens: number;
     cacheRead: number;
     cacheCreation: number;
-    costUSD: number;
+    /** Media generation call count (image/video/music/tts/3d) */
+    mediaCalls: number;
+    /** Total seconds of media output (video, music) */
+    mediaDurationSeconds: number;
+    /** Total characters processed (TTS) */
+    mediaCharacters: number;
 }
 /** Snapshot of the session state for persistence / restore */
-export interface SessionCostSnapshot {
+export interface SessionUsageSnapshot {
     sessionId: string;
-    totalCostUSD: number;
     modelUsage: Record<string, ModelUsage>;
     totalInputTokens: number;
     totalOutputTokens: number;
     turnCount: number;
     lastSavedAt: number;
 }
+/** @deprecated Use SessionUsageSnapshot. Kept for persistence compat. */
+export type SessionCostSnapshot = SessionUsageSnapshot;
 /** Thresholds for background memory extraction — CC sessionMemory.ts parity */
 export interface MemoryExtractionThresholds {
     /** Token threshold before FIRST extraction (default 10000) */
@@ -45,7 +51,6 @@ export interface MemoryExtractionThresholds {
 export declare class SessionState {
     readonly sessionId: string;
     private _trustAccepted;
-    private _totalCostUSD;
     private _modelUsage;
     private _totalInputTokens;
     private _totalOutputTokens;
@@ -60,7 +65,6 @@ export declare class SessionState {
     constructor(sessionId: string, thresholds?: Partial<MemoryExtractionThresholds>);
     get trustAccepted(): boolean;
     setTrustAccepted(accepted: boolean): void;
-    get totalCostUSD(): number;
     get totalInputTokens(): number;
     get totalOutputTokens(): number;
     get turnCount(): number;
@@ -71,12 +75,17 @@ export declare class SessionState {
     getAllModelUsage(): Record<string, ModelUsage>;
     /**
      * Add usage from an API response — CC addToTotalSessionCost() parity.
+     * Tracks token counts only; pricing is handled by Hub/Admin.
      *
      * @param usage - Token counts from the API response
      * @param model - Model identifier
-     * @param costUSD - Calculated cost (caller computes based on pricing)
      */
-    addUsage(usage: TokenUsage, model: string, costUSD?: number): void;
+    addUsage(usage: TokenUsage, model: string): void;
+    /**
+     * Add usage from a media generation call (non-token billing).
+     * Tracks quantities only (calls, seconds, characters); pricing is Hub/Admin's job.
+     */
+    addMediaUsage(model: string, billingUnit: string, quantity: number): void;
     /** Record a tool call (for extraction threshold tracking) */
     recordToolCall(): void;
     /** Increment turn count */
@@ -98,7 +107,7 @@ export declare class SessionState {
      * Create a snapshot for persistence.
      * CC saveCurrentSessionCosts() parity.
      */
-    createSnapshot(): SessionCostSnapshot;
+    createSnapshot(): SessionUsageSnapshot;
     /**
      * Restore from a previous snapshot.
      * CC setCostStateForRestore() parity.
@@ -106,7 +115,7 @@ export declare class SessionState {
      * GUARD: Only restores if the snapshot's sessionId matches this session.
      * Prevents cross-session cost leakage (CC's lastSessionId guard).
      */
-    restoreFromSnapshot(snapshot: SessionCostSnapshot): boolean;
+    restoreFromSnapshot(snapshot: SessionUsageSnapshot): boolean;
     /** Register a state change listener. Returns unsubscribe function. */
     onStateChange(listener: () => void): () => void;
     private notifyListeners;

package/dist/types/skills/memory/qmemory-adapter.d.ts

@@ -35,6 +35,7 @@ export interface QMemoryHealthStatus {
  */
 export declare function createQMemoryAdapter(config: QMemoryAdapterConfig): MemoryProvider & {
     health(): Promise<QMemoryHealthStatus>;
+    remove(memoryId: string): Promise<boolean>;
     ingestExtracted(items: ExtractedMemoryItem[], userId: string, options?: MemoryIngestOptions): Promise<{
         memoriesAdded: number;
     }>;

package/dist/types/skills/tools/shell/shell-exec.d.ts

@@ -14,6 +14,8 @@ export interface ExecOptions {
     shouldAutoBackground?: boolean;
     /** When provided, stdout is piped and this callback fires per chunk. */
     onStdout?: (data: string) => void;
+    /** Per-call CWD override. When set, spawn uses this instead of the session CWD. */
+    cwd?: string;
 }
 /**
  * Set the shell provider for this session.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qlogicagent",
-  "version": "0.6.0",
+  "version": "1.0.0",
   "description": "XiaozhiClaw Agent CLI — subprocess architecture (JSON-RPC over stdio)",
   "type": "module",
   "main": "dist/index.js",