sailfork / t3code-github / packages/ provider-muse/ src/ server/ sdk.ts
// @effect-diagnostics globalTimers:off
// The SDK owns process shutdown; native deadlines cover initialize before an Effect resource exists.
// @effect-diagnostics-next-line nodeBuiltinImport:off -- FileSystem.realPath is Node's JS realpath; museCanonicalPath needs the native one.
import * as NodeFSP from "node:fs/promises";
import {
spawnMspConnection,
type Connection,
type ProcessExit,
type SpawnedMspConnection,
} from "@muse-code/sdk";
import type { RuntimeMode } from "@t3tools/contracts";
import * as HostProcess from "@t3tools/shared/HostProcess";
import { SpawnExecutableResolution } from "@t3tools/shared/shell";
import * as Effect from "effect/Effect";
import * as Schema from "effect/Schema";
export class MuseSdkError extends Schema.TaggedError<MuseSdkError>()("MuseSdkError", {
operation: Schema.String,
cause: Schema.Defect(),
}) {
override get message(): string {
return `Muse SDK ${this.operation} failed.`;
}
}
export interface MuseSdkHost {
readonly connection: Pick<
Connection,
| "command"
| "request"
| "mintCommandId"
| "onNotification"
| "onServerRequest"
| "onProtocolError"
| "closed"
>;
readonly initializeResult: Pick<SpawnedMspConnection["initializeResult"], "grantedCapabilities"> &
Partial<Pick<SpawnedMspConnection["initializeResult"], "museHome">>;
readonly exited: Promise<ProcessExit>;
readonly stderrTail?: () => ReadonlyArray<string>;
readonly close: () => Promise<void>;
}
export interface MuseLaunch {
readonly command: string;
readonly args: ReadonlyArray<string>;
}
export interface MuseSdkHostOptions {
readonly binaryPath: string;
readonly launchArgs?: ReadonlyArray<string>;
readonly launch?: MuseLaunch;
readonly cwd?: string;
readonly environment?: NodeJS.ProcessEnv;
readonly runtimeMode?: RuntimeMode;
readonly readOnly?: boolean;
/** Read-only generation needs session logging for turn/item notifications. */
readonly sessionLogging?: boolean;
readonly signal?: AbortSignal;
readonly startupTimeoutMs?: number;
readonly onProcessExit?: (exit: ProcessExit) => void;
}
export function makeMuseEnvironment(
environment: NodeJS.ProcessEnv = process.env,
): NodeJS.ProcessEnv {
return {
...Object.fromEntries(
Object.keys(environment)
.filter((key) => key.toUpperCase() !== "META_API_KEY")
.map((key) => [key, environment[key]]),
),
MUSE_NO_AUTO_UPDATE: "1",
};
}
export function museVerbatimPath(path: string): string {
if (path.startsWith("\\\\?\\")) return path;
return path.startsWith("\\\\") ? `\\\\?\\UNC\\${path.slice(2)}` : `\\\\?\\${path}`;
}
// Native realpath corrects filesystem case as well as resolving symlinks.
export const museCanonicalPath = Effect.fn("museCanonicalPath")(function* (path: string) {
return yield* Effect.tryPromise({
try: () => NodeFSP.realpath(path),
catch: (cause) => new MuseSdkError({ operation: "realpath", cause }),
}).pipe(Effect.orElseSucceed(() => path));
});
// Windows turn roots need verbatim form; launch cmd.exe with the plain canonical path.
export const museWorkspaceRoot = Effect.fn("museWorkspaceRoot")(function* (path: string) {
if ((yield* HostProcess.Platform) !== "win32") return yield* museCanonicalPath(path);
const canonical = yield* Effect.tryPromise({
try: () => NodeFSP.realpath(path),
catch: (cause) => new MuseSdkError({ operation: "realpath", cause }),
}).pipe(
// A verbatim path takes `/` literally, so an unresolved root needs Windows separators.
Effect.orElseSucceed(() => path.replaceAll("/", "\\")),
);
return museVerbatimPath(canonical);
});
function windowsEnvironmentValue(environment: NodeJS.ProcessEnv, name: string) {
const key = Object.keys(environment).find(
(candidate) => candidate.toUpperCase() === name.toUpperCase(),
);
return key === undefined ? undefined : environment[key];
}
/** Resolve Windows launchers with PATHEXT and run .cmd/.bat under cmd.exe; SDK spawn has no shell. */
export const museLaunch = Effect.fn("museLaunch")(function* (
binaryPath: string,
environment?: NodeJS.ProcessEnv,
): Effect.fn.Return<MuseLaunch> {
if ((yield* HostProcess.Platform) !== "win32") return { command: binaryPath, args: [] };
const env = environment ?? (yield* HostProcess.Environment);
const resolveExecutable = yield* SpawnExecutableResolution;
const resolved = resolveExecutable(binaryPath, "win32", env) ?? binaryPath;
if (!/\.(?:cmd|bat)$/i.test(resolved)) return { command: resolved, args: [] };
const systemRoot = windowsEnvironmentValue(env, "SystemRoot");
return {
command:
windowsEnvironmentValue(env, "ComSpec") ??
(systemRoot ? `${systemRoot}\\System32\\cmd.exe` : "cmd.exe"),
// /d prevents AutoRun stdout; bare @ preserves quoted paths that cmd /c would unquote.
args: [
"/d",
"/c",
...(/\s/.test(resolved) ? ["@", resolved] : [resolved.replace(/[()&<>@^|]/g, "^Loading Sailfork
amp;")]),
],
};
});
export function museApprovalMode(runtimeMode: RuntimeMode) {
return runtimeMode === "full-access" ? "allowAll" : "promptUnmatched";
}
// Select explicitly; Muse defaults may let an AI reviewer decide approvals.
export function musePermissionProfile(runtimeMode: RuntimeMode) {
return runtimeMode === "full-access" ? ":unrestricted" : ":ask-me";
}
export function museServeArgs(
options: Pick<MuseSdkHostOptions, "readOnly" | "sessionLogging" | "runtimeMode">,
) {
const args = ["serve"];
if (options.readOnly) {
args.push("--disable-shell", "--disable-write");
if (options.sessionLogging !== true) args.push("--no-session-log");
} else {
args.push("--trust-workspace");
if (options.runtimeMode === "full-access") args.push("--disable-sandbox");
}
return args;
}
export function museInitializeParams(readOnly = false) {
return {
clientInfo: { name: "t3_code", title: "T3 Code", version: "1" },
capabilities: { requestedCapabilities: readOnly ? [] : ["sessionMcp"] },
};
}
/** Owns cleanup before the handshake, even if initialize never replies. */
export async function createMuseSdkHost(
options: MuseSdkHostOptions,
spawn: typeof spawnMspConnection = spawnMspConnection,
): Promise<MuseSdkHost> {
options.signal?.throwIfAborted();
const launch = options.launch ?? { command: options.binaryPath, args: [] };
const handshake = spawn({
command: launch.command,
args: [...launch.args, ...(options.launchArgs ?? []), ...museServeArgs(options)],
...(options.cwd ? { cwd: options.cwd } : {}),
env: options.environment ?? makeMuseEnvironment(),
shutdownTimeoutMs: 10_000,
...(options.onProcessExit ? { onProcessExit: options.onProcessExit } : {}),
});
let closePromise: Promise<void> | undefined;
const close = () => {
options.signal?.removeEventListener("abort", onAbort);
return (closePromise ??= handshake.close().then(() => undefined));
};
let rejectStartup: (reason: unknown) => void = () => {};
const onAbort = () => {
rejectStartup(options.signal?.reason ?? new Error("Muse SDK startup aborted."));
void close().catch(() => {});
};
const interrupted = new Promise<never>((_resolve, reject) => {
rejectStartup = reject;
});
options.signal?.addEventListener("abort", onAbort, { once: true });
if (options.signal?.aborted) onAbort();
const timer = setTimeout(
() => rejectStartup(new Error("Muse SDK initialization timed out.")),
options.startupTimeoutMs ?? 20_000,
);
timer.unref();
try {
const host = await Promise.race([
handshake.initialize(museInitializeParams(options.readOnly)),
interrupted,
]);
if (host.initializeResult.schema?.version !== 1) {
throw new Error("Muse SDK returned an unsupported protocol envelope version.");
}
// Fingerprint warnings permit additive schema changes; successful initialization proves readiness.
return {
connection: host.connection,
initializeResult: host.initializeResult,
exited: host.exited,
stderrTail: () => handshake.child.stderrTail,
close,
};
} catch (error) {
await close();
throw error;
} finally {
clearTimeout(timer);
}
}
/** Cancellation waits for native shutdown before callers release startup resources. */
export const createMuseSdkHostEffect = Effect.fn("createMuseSdkHostEffect")(function* (
options: Omit<MuseSdkHostOptions, "signal">,
createHost: typeof createMuseSdkHost = createMuseSdkHost,
) {
const launch = options.launch ?? (yield* museLaunch(options.binaryPath, options.environment));
let startup: Promise<MuseSdkHost> | undefined;
return yield* Effect.tryPromise({
try: (signal) => {
startup = createHost({ ...options, launch, signal });
return startup;
},
catch: (cause) => new MuseSdkError({ operation: "start", cause }),
}).pipe(
Effect.onInterrupt(() =>
Effect.promise(async () => {
await startup?.then(
(host) => host.close(),
() => {},
);
}),
),
);
});