@klarkxy/dsh-fusion 0.1.0

package/lib/contracts.d.ts

@@ -0,0 +1,173 @@
+//#region src/contracts.d.ts
+/** Public, browser-safe Fusion records. Native Sessions remain the transcript authority. */
+declare const FUSION_PLUGIN = "@klarkxy/dsh-fusion";
+declare const FUSION_RPC_CHANNEL = "/dsh-fusion";
+declare const FUSION_PURPOSE = "fusion.sidekick";
+declare const FUSION_TOOLS: readonly ["fusion_delegate", "fusion_report", "fusion_review", "fusion_read", "fusion_decide", "fusion_cancel"];
+type FusionProfile = 'generic' | 'writing';
+type TaskState = 'dispatching' | 'working' | 'decision' | 'review' | 'accepted' | 'cancelled' | 'failed' | 'interrupted';
+type ModelRoute = {
+  provider: string;
+  model: string;
+  reasoningEffort?: string;
+};
+type Json = null | boolean | number | string | Json[] | {
+  [key: string]: Json;
+};
+interface FusionActor {
+  sessionId: string;
+  parentSessionId?: string;
+  project: string;
+}
+interface FusionBrief {
+  title: string;
+  goal: string;
+  context: string;
+  constraints: string[];
+  acceptance: string[];
+}
+/** A domain-owned, versioned destination. The Writer cannot replace this target. */
+interface FusionTarget {
+  domain: string;
+  data: {
+    [key: string]: Json;
+  };
+}
+interface FusionCandidate {
+  id: string;
+  taskRevision: number;
+  revision: number;
+  text: string;
+  hash: string;
+  report: string;
+  createdAt: number;
+}
+interface FusionReview {
+  candidateId: string;
+  candidateHash: string;
+  verdict: 'accept' | 'revise' | 'reject';
+  feedback: string;
+  createdAt: number;
+}
+interface FusionTask {
+  id: string;
+  revision: number;
+  state: TaskState;
+  brief: FusionBrief;
+  target?: FusionTarget;
+  candidates: FusionCandidate[];
+  reviews: FusionReview[];
+  messageIds: string[];
+  dispatchId: string;
+  reportIds: string[];
+  /** Last report whose native Lead notification was confirmed and durably recorded. */
+  notifiedReportId?: string;
+  /** Whether the latest native inbox submission is known to have been accepted. */
+  delivery: 'pending' | 'accepted' | 'uncertain';
+  decision?: string;
+  error?: string;
+  cleanup?: 'pending' | 'done' | 'failed';
+  adoption?: 'pending' | 'applied' | 'dismissed' | 'conflict';
+  /** Persist before filesystem mutation; never replay an uncertain write. */
+  application?: {
+    id: string;
+    candidateId: string;
+    candidateHash: string;
+    path: string;
+    beforeVersion: string;
+    afterHash: string;
+    state: 'pending' | 'applied' | 'conflict';
+    version?: string;
+  };
+  createdAt: number;
+  updatedAt: number;
+}
+interface FusionPair {
+  id: string;
+  leadSessionId: string;
+  childSessionId: string;
+  project: string;
+  profile: FusionProfile;
+  route: ModelRoute;
+  /** A successful initial inbox admission, not a claim about provider prompt caching. */
+  established: boolean;
+  tasks: FusionTask[];
+  createdAt: number;
+}
+interface FusionState {
+  version: 1;
+  revision: number;
+  pairs: FusionPair[];
+}
+interface FusionStore {
+  load(): FusionState;
+  save(next: FusionState): Promise<void>;
+}
+/** This port adapts native subagents. It must not own another Agent loop or inbox. */
+interface FusionNative {
+  dispatch(input: {
+    pair: FusionPair;
+    task: FusionTask;
+    prompt: string;
+    signal: AbortSignal;
+  }): Promise<{
+    messageId: string;
+  }>;
+  notify(input: {
+    pair: FusionPair;
+    task: FusionTask;
+    actor: FusionActor;
+    text: string;
+    signal: AbortSignal;
+  }): Promise<void>;
+  stop(pair: FusionPair, stopLead: boolean): Promise<void>;
+}
+interface FusionStatus {
+  available: boolean;
+  profile: FusionProfile;
+  configured: boolean;
+  revision?: number;
+  error?: string;
+  pair?: FusionPair;
+  /** Cumulative native-session figures, not an estimate of this task's cost. */
+  usage?: {
+    leadTokens: number | null;
+    sidekickTokens: number | null;
+    cost: null;
+  };
+  activity?: {
+    lead: string;
+    sidekick: string;
+  };
+}
+type RpcResult<T = unknown> = {
+  ok: true;
+  value: T;
+} | {
+  ok: false;
+  error: {
+    code: string;
+    message: string;
+  };
+};
+declare const isWorking: (state: TaskState) => boolean;
+declare const emptyFusionState: () => FusionState;
+/** Browser commands identify stored authority; no command accepts replacement candidate text. */
+interface FusionCandidateAction {
+  sessionId: string;
+  taskId: string;
+  taskRevision: number;
+  candidateId: string;
+  hash: string;
+}
+interface FusionPreview {
+  path: string;
+  before: string;
+  after: string;
+  version: string;
+  candidateId: string;
+  hash: string;
+}
+//#endregion
+export { FUSION_PLUGIN, FUSION_PURPOSE, FUSION_RPC_CHANNEL, FUSION_TOOLS, FusionActor, FusionBrief, FusionCandidate, FusionCandidateAction, FusionNative, FusionPair, FusionPreview, FusionProfile, FusionReview, FusionState, FusionStatus, FusionStore, FusionTarget, FusionTask, Json, ModelRoute, RpcResult, TaskState, emptyFusionState, isWorking };
+//# sourceMappingURL=contracts.d.ts.map

package/lib/contracts.js

@@ -0,0 +1,28 @@
+//#region src/contracts.ts
+/** Public, browser-safe Fusion records. Native Sessions remain the transcript authority. */
+const FUSION_PLUGIN = "@klarkxy/dsh-fusion";
+const FUSION_RPC_CHANNEL = "/dsh-fusion";
+const FUSION_PURPOSE = "fusion.sidekick";
+const FUSION_TOOLS = [
+	"fusion_delegate",
+	"fusion_report",
+	"fusion_review",
+	"fusion_read",
+	"fusion_decide",
+	"fusion_cancel"
+];
+const isWorking = (state) => [
+	"dispatching",
+	"working",
+	"decision",
+	"review"
+].includes(state);
+const emptyFusionState = () => ({
+	version: 1,
+	revision: 0,
+	pairs: []
+});
+//#endregion
+export { FUSION_PLUGIN, FUSION_PURPOSE, FUSION_RPC_CHANNEL, FUSION_TOOLS, emptyFusionState, isWorking };
+
+//# sourceMappingURL=contracts.js.map

package/lib/contracts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contracts.js","names":[],"sources":["../src/contracts.ts"],"sourcesContent":["/** Public, browser-safe Fusion records. Native Sessions remain the transcript authority. */\nexport const FUSION_PLUGIN = '@klarkxy/dsh-fusion'\nexport const FUSION_RPC_CHANNEL = '/dsh-fusion'\nexport const FUSION_PURPOSE = 'fusion.sidekick'\nexport const FUSION_TOOLS = ['fusion_delegate', 'fusion_report', 'fusion_review', 'fusion_read', 'fusion_decide', 'fusion_cancel'] as const\nexport type FusionProfile = 'generic' | 'writing'\nexport type TaskState = 'dispatching' | 'working' | 'decision' | 'review' | 'accepted' | 'cancelled' | 'failed' | 'interrupted'\nexport type ModelRoute = { provider: string; model: string; reasoningEffort?: string }\nexport type Json = null | boolean | number | string | Json[] | { [key: string]: Json }\nexport interface FusionActor { sessionId: string; parentSessionId?: string; project: string }\nexport interface FusionBrief {\n  title: string\n  goal: string\n  context: string\n  constraints: string[]\n  acceptance: string[]\n}\n/** A domain-owned, versioned destination. The Writer cannot replace this target. */\nexport interface FusionTarget { domain: string; data: { [key: string]: Json } }\nexport interface FusionCandidate {\n  id: string\n  taskRevision: number\n  revision: number\n  text: string\n  hash: string\n  report: string\n  createdAt: number\n}\nexport interface FusionReview {\n  candidateId: string\n  candidateHash: string\n  verdict: 'accept' | 'revise' | 'reject'\n  feedback: string\n  createdAt: number\n}\nexport interface FusionTask {\n  id: string\n  revision: number\n  state: TaskState\n  brief: FusionBrief\n  target?: FusionTarget\n  candidates: FusionCandidate[]\n  reviews: FusionReview[]\n  messageIds: string[]\n  dispatchId: string\n  reportIds: string[]\n  /** Last report whose native Lead notification was confirmed and durably recorded. */\n  notifiedReportId?: string\n  /** Whether the latest native inbox submission is known to have been accepted. */\n  delivery: 'pending' | 'accepted' | 'uncertain'\n  decision?: string\n  error?: string\n  cleanup?: 'pending' | 'done' | 'failed'\n  adoption?: 'pending' | 'applied' | 'dismissed' | 'conflict'\n  /** Persist before filesystem mutation; never replay an uncertain write. */\n  application?: {\n    id: string; candidateId: string; candidateHash: string; path: string\n    beforeVersion: string; afterHash: string; state: 'pending' | 'applied' | 'conflict'; version?: string\n  }\n  createdAt: number\n  updatedAt: number\n}\nexport interface FusionPair {\n  id: string\n  leadSessionId: string\n  childSessionId: string\n  project: string\n  profile: FusionProfile\n  route: ModelRoute\n  /** A successful initial inbox admission, not a claim about provider prompt caching. */\n  established: boolean\n  tasks: FusionTask[]\n  createdAt: number\n}\nexport interface FusionState { version: 1; revision: number; pairs: FusionPair[] }\nexport interface FusionStore { load(): FusionState; save(next: FusionState): Promise<void> }\n/** This port adapts native subagents. It must not own another Agent loop or inbox. */\nexport interface FusionNative {\n  dispatch(input: { pair: FusionPair; task: FusionTask; prompt: string; signal: AbortSignal }): Promise<{ messageId: string }>\n  notify(input: { pair: FusionPair; task: FusionTask; actor: FusionActor; text: string; signal: AbortSignal }): Promise<void>\n  stop(pair: FusionPair, stopLead: boolean): Promise<void>\n}\nexport interface FusionStatus {\n  available: boolean\n  profile: FusionProfile\n  configured: boolean\n  revision?: number\n  error?: string\n  pair?: FusionPair\n  /** Cumulative native-session figures, not an estimate of this task's cost. */\n  usage?: { leadTokens: number | null; sidekickTokens: number | null; cost: null }\n  activity?: { lead: string; sidekick: string }\n}\nexport type RpcResult<T = unknown> = { ok: true; value: T } | { ok: false; error: { code: string; message: string } }\nexport const isWorking = (state: TaskState): boolean => ['dispatching', 'working', 'decision', 'review'].includes(state)\nexport const emptyFusionState = (): FusionState => ({ version: 1, revision: 0, pairs: [] })\n\n/** Browser commands identify stored authority; no command accepts replacement candidate text. */\nexport interface FusionCandidateAction {\n  sessionId: string; taskId: string; taskRevision: number; candidateId: string; hash: string\n}\nexport interface FusionPreview {\n  path: string; before: string; after: string; version: string\n  candidateId: string; hash: string\n}\n"],"mappings":";;AACA,MAAa,gBAAgB;AAC7B,MAAa,qBAAqB;AAClC,MAAa,iBAAiB;AAC9B,MAAa,eAAe;CAAC;CAAmB;CAAiB;CAAiB;CAAe;CAAiB;AAAe;AA0FjI,MAAa,aAAa,UAA8B;CAAC;CAAe;CAAW;CAAY;AAAQ,CAAC,CAAC,SAAS,KAAK;AACvH,MAAa,0BAAuC;CAAE,SAAS;CAAG,UAAU;CAAG,OAAO,CAAC;AAAE"}

package/lib/host-contracts.d.ts

@@ -0,0 +1,38 @@
+import { FusionActor, FusionCandidate, FusionTarget } from "./contracts.js";
+//#region src/host-contracts.d.ts
+/** Implemented by the Editor Host; the standalone plugin has no manuscript dependency. */
+interface FusionWritingHost {
+  matches(header: {
+    agentPreset?: string;
+  }): boolean;
+  /** Exact native names, checked again by the execution guard, never just hidden from the model. */
+  readonly writerTools: readonly string[];
+  allowLeadTool(name: string, args: unknown): boolean;
+  capture(actor: FusionActor, input: unknown, signal: AbortSignal): Promise<FusionTarget>;
+  /** Holds the existing workspace write lock, including dirty-draft and version checks. */
+  transact<T>(actor: FusionActor, target: FusionTarget, candidate: FusionCandidate, signal: AbortSignal, run: (access: FusionApplicationAccess) => Promise<T>): Promise<T>;
+}
+interface FusionApplicationPreview {
+  path: string;
+  before: string;
+  after: string;
+  /** Empty only for an exclusive create whose destination does not exist. */
+  version: string;
+}
+interface FusionApplicationAccess {
+  /** Read without requiring the old baseline, for reconciling an already persisted intent. */
+  inspect(): Promise<{
+    text: string;
+    version: string;
+  } | undefined>;
+  /** Revalidates original target and basis and refuses any unsaved author draft. */
+  prepare(): Promise<FusionApplicationPreview>;
+  /** Must repeat relevant checks immediately before a version-checked write. */
+  commit(expectedVersion: string): Promise<{
+    path: string;
+    version: string;
+  }>;
+}
+//#endregion
+export { FusionApplicationAccess, FusionApplicationPreview, FusionWritingHost };
+//# sourceMappingURL=host-contracts.d.ts.map

package/lib/host-contracts.js

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

package/lib/index.d.ts

@@ -0,0 +1,134 @@
+import { FUSION_PLUGIN, FUSION_PURPOSE, FUSION_RPC_CHANNEL, FUSION_TOOLS, FusionActor, FusionBrief, FusionCandidate, FusionCandidateAction, FusionNative, FusionPair, FusionPreview, FusionProfile, FusionReview, FusionState, FusionStatus, FusionStore, FusionTarget, FusionTask, Json, ModelRoute, RpcResult, TaskState, emptyFusionState, isWorking } from "./contracts.js";
+import { FusionApplicationAccess, FusionApplicationPreview, FusionWritingHost } from "./host-contracts.js";
+import { Context } from "@deepseek-ai/cordis";
+import { Agent } from "@deepseek-ai/dsh-agent";
+import { AiServices } from "@klarkxy/dsh-ai-services/contracts";
+//#region src/service.d.ts
+/** Business records only. The native continuation manager owns Agents and all message scheduling. */
+declare class FusionService {
+  private state;
+  private pending;
+  private enabled;
+  private generation;
+  private storageFailed;
+  private readonly controller;
+  private readonly dispatches;
+  private readonly applications;
+  private readonly notifications;
+  private readonly inFlight;
+  private readonly ready;
+  private readonly store;
+  private readonly inspectAdmission?;
+  private readonly native;
+  private readonly now;
+  private readonly id;
+  constructor(input: {
+    store: FusionStore;
+    native: FusionNative;
+    inspectAdmission?: (pair: FusionPair, signal: AbortSignal) => Promise<'present' | 'absent'>;
+    now?: () => number;
+    id?: () => string;
+  });
+  get active(): boolean;
+  initialized(): Promise<void>;
+  snapshot(): FusionState;
+  pairFor(sessionId: string): FusionPair | undefined;
+  role(sessionId: string): 'lead' | 'sidekick' | undefined;
+  private persist;
+  private change;
+  private owned;
+  private task;
+  private isCurrent;
+  private track;
+  private abortNotifications;
+  delegate(actor: FusionActor, input: {
+    profile: FusionProfile;
+    route: ModelRoute;
+    brief: FusionBrief;
+    target?: FusionTarget;
+    signal: AbortSignal;
+  }): Promise<FusionTask>;
+  private roleIsChild;
+  private dispatch;
+  private prompt;
+  report(actor: FusionActor, input: {
+    taskId: string;
+    taskRevision: number;
+    reportId: string;
+    kind: 'candidate' | 'decision';
+    text: string;
+    report?: string;
+    signal: AbortSignal;
+  }): Promise<FusionTask>;
+  read(actor: FusionActor, taskId: string, candidateId?: string): {
+    task: FusionTask;
+    candidate?: FusionCandidate;
+  };
+  review(actor: FusionActor, input: {
+    taskId: string;
+    taskRevision: number;
+    candidateId: string;
+    hash: string;
+    verdict: 'accept' | 'revise' | 'reject';
+    feedback: string;
+    signal: AbortSignal;
+  }): Promise<FusionTask>;
+  decide(actor: FusionActor, input: {
+    taskId: string;
+    taskRevision: number;
+    feedback: string;
+    signal: AbortSignal;
+  }): Promise<FusionTask>;
+  cancel(actor: FusionActor, taskId: string, taskRevision: number, stopLead?: boolean): Promise<void>;
+  executionInterrupted(actor: FusionActor, reason: string, expected?: {
+    taskId: string;
+    revision: number;
+  }): Promise<void>;
+  /** Explicit recovery only: saved content is re-notified, never dispatched to the Writer. */
+  recover(actor: FusionActor, taskId: string, taskRevision: number, outerSignal: AbortSignal): Promise<FusionTask>;
+  private candidateAction;
+  /** Also used by status. An uncertain filesystem mutation is inspected, never replayed. */
+  reconcile(actor: FusionActor, host: FusionWritingHost, signal: AbortSignal): Promise<void>;
+  preview(actor: FusionActor, input: FusionCandidateAction, host: FusionWritingHost, signal: AbortSignal): Promise<FusionPreview>;
+  applyCandidate(actor: FusionActor, input: FusionCandidateAction & {
+    expectedVersion: string;
+  }, host: FusionWritingHost, outerSignal: AbortSignal): Promise<FusionTask>;
+  dismiss(actor: FusionActor, input: FusionCandidateAction): Promise<FusionTask>;
+  /** Domain Host only: never expose an RPC that lets a browser claim a file was applied. */
+  adoption(leadSessionId: string, taskId: string, candidateId: string, state: 'applied' | 'dismissed' | 'conflict'): Promise<void>;
+  /** Stops owned work only. Invalidate synchronously, then await admissions and cleanup. */
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/runtime.d.ts
+declare class FusionRuntime {
+  readonly service: FusionService;
+  private readonly ctx;
+  private readonly ai;
+  private readonly disposers;
+  private readonly installed;
+  private readonly pendingNoticeClaims;
+  private closing?;
+  constructor(ctx: Context, store: FusionStore, ai: AiServices);
+  private inspectAdmission;
+  private checkRoute;
+  actor(agent: Agent): FusionActor;
+  private writing;
+  private profile;
+  private childTools;
+  start(): Promise<void>;
+  private install;
+  private uninstall;
+  delegate(agent: Agent, input: unknown, signal: AbortSignal): Promise<FusionTask>;
+  private rpcActor;
+  rpc(endpoint: string, payload: unknown, signal: AbortSignal): Promise<unknown>;
+  dispose(): Promise<void>;
+}
+//#endregion
+//#region src/index.d.ts
+declare const name = "@klarkxy/dsh-fusion";
+declare const inject: readonly ["agents", "subagents", "tools", "systemPrompt", "sessions", "sessionQuery", "sessionProjections", "storageDomain", "aiServices", "connection", "webServer"];
+declare function apply(ctx: Context): Promise<void>;
+//#endregion
+export { type FUSION_PLUGIN, type FUSION_PURPOSE, type FUSION_RPC_CHANNEL, type FUSION_TOOLS, type FusionActor, type FusionApplicationAccess, type FusionApplicationPreview, type FusionBrief, type FusionCandidate, type FusionCandidateAction, type FusionNative, type FusionPair, type FusionPreview, type FusionProfile, type FusionReview, FusionRuntime, type FusionState, type FusionStatus, type FusionStore, type FusionTarget, type FusionTask, type FusionWritingHost, type Json, type ModelRoute, type RpcResult, type TaskState, apply, type emptyFusionState, inject, type isWorking, name };
+//# sourceMappingURL=index.d.ts.map