Skip to content

Commit f7f9b83

Browse files
committed
fix(desktop): unpack the t3 Claude plugin so handoff works in packaged apps
The plugin shipped inside app.asar (and inside the Windows server.asar sidecar), where only the server's asar-aware Electron fs could see it. The `claude` subprocess is a plain process, so the plugin loaded nowhere while skill discovery — reading through that same fs — still advertised t3:handoff in the picker. Selecting it did nothing. Unpack claude-plugin in both archives, resolve the plugin to its .unpacked twin (and report nothing plus a warning when there is no twin, instead of handing over a path that exists only for the server), and inject the CLI entry and the runtime that can read it so the bin/t3 shim reaches a bundle that stays packed.
1 parent 7efe229 commit f7f9b83

13 files changed

Lines changed: 234 additions & 32 deletions

File tree

‎apps/server/claude-plugin/bin/t3‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,17 @@
11
#!/bin/sh
2-
# t3 CLI shim, shipped with the T3 Code Claude plugin. Sessions spawned by a dev
3-
# server have no installed `t3` on PATH, so T3 Code injects this shim's path as
4-
# $T3_CLI. It resolves the CLI entry relative to itself: the monorepo source
5-
# layout first, then the bundled dist layout.
2+
# t3 CLI shim, shipped with the T3 Code Claude plugin. Sessions have no
3+
# installed `t3` on PATH, so T3 Code injects this shim's path as $T3_CLI.
4+
#
5+
# The server also injects the exact CLI entry ($T3_CLI_ENTRY) and the runtime
6+
# to read it with ($T3_CLI_RUNTIME): in a packaged desktop app the entry lives
7+
# inside an asar archive, which only the Electron binary can read, and it does
8+
# so through ELECTRON_RUN_AS_NODE (a plain `node` ignores that variable).
9+
if [ -n "$T3_CLI_ENTRY" ]; then
10+
ELECTRON_RUN_AS_NODE=1 exec "${T3_CLI_RUNTIME:-node}" "$T3_CLI_ENTRY" "$@"
11+
fi
12+
13+
# Fallback for sessions spawned without that env: resolve the entry relative to
14+
# this shim, source layout first, then the bundled dist layout.
615
dir="$(cd "$(dirname "$0")" && pwd)"
716
for entry in "$dir/../../src/bin.ts" "$dir/../../bin.mjs"; do
817
if [ -f "$entry" ]; then

‎apps/server/scripts/cli.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,7 @@ const buildCmd = Command.make(
174174
}
175175

176176
// The t3 Claude plugin is resolved at runtime from dist/claude-plugin next
177-
// to the bundle (see resolveT3ClaudePluginDir); without this copy bundled
177+
// to the bundle (see resolveT3ClaudePluginLocation); without this copy bundled
178178
// builds silently lose the t3:handoff skill.
179179
const pluginSource = path.join(serverDir, "claude-plugin");
180180
const pluginTarget = path.join(serverDir, "dist/claude-plugin");

‎apps/server/src/handoff/callbackEnvironment.test.ts‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,3 +28,23 @@ it("omits T3_CLI when no shim path is available", () => {
2828
assert.equal(environment.T3_CLI, undefined);
2929
assert.equal(environment.T3_SERVER_ORIGIN, "http://127.0.0.1:3284");
3030
});
31+
32+
it("injects the CLI entry and the runtime that can read it", () => {
33+
const environment = makeHandoffCallbackEnvironment(mcpSessionConfig, {
34+
cliShimPath: "/app.asar.unpacked/apps/server/dist/claude-plugin/bin/t3",
35+
cliEntryPath: "/app.asar/apps/server/dist/bin.mjs",
36+
cliRuntimePath: "/Applications/T3 Code.app/Contents/MacOS/T3 Code",
37+
});
38+
39+
assert.equal(environment.T3_CLI_ENTRY, "/app.asar/apps/server/dist/bin.mjs");
40+
assert.equal(environment.T3_CLI_RUNTIME, "/Applications/T3 Code.app/Contents/MacOS/T3 Code");
41+
});
42+
43+
it("omits the runtime when there is no entry to read with it", () => {
44+
const environment = makeHandoffCallbackEnvironment(mcpSessionConfig, {
45+
cliRuntimePath: "/usr/bin/node",
46+
});
47+
48+
assert.equal(environment.T3_CLI_ENTRY, undefined);
49+
assert.equal(environment.T3_CLI_RUNTIME, undefined);
50+
});

‎apps/server/src/handoff/callbackEnvironment.ts‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,24 @@
1414
* @module handoff/callbackEnvironment
1515
*/
1616
import type { McpProviderSessionConfig } from "../mcp/McpProviderSession.ts";
17-
import { T3_CLI_ENV, T3_SERVER_ORIGIN_ENV, T3_SERVER_TOKEN_ENV, T3_THREAD_ID_ENV } from "./protocol.ts";
17+
import {
18+
T3_CLI_ENTRY_ENV,
19+
T3_CLI_ENV,
20+
T3_CLI_RUNTIME_ENV,
21+
T3_SERVER_ORIGIN_ENV,
22+
T3_SERVER_TOKEN_ENV,
23+
T3_THREAD_ID_ENV,
24+
} from "./protocol.ts";
1825

1926
export function makeHandoffCallbackEnvironment(
2027
session: McpProviderSessionConfig,
2128
options?: {
2229
/** Absolute path of the plugin's `bin/d` shim; omitted → sessions fall back to `d` on PATH. */
2330
readonly cliShimPath?: string;
31+
/** CLI entry the shim runs; omitted → the shim resolves one next to itself. */
32+
readonly cliEntryPath?: string;
33+
/** Executable that reads the entry; omitted → the shim falls back to `node`. */
34+
readonly cliRuntimePath?: string;
2435
},
2536
): Record<string, string> {
2637
const origin = new URL(session.endpoint).origin;
@@ -32,5 +43,9 @@ export function makeHandoffCallbackEnvironment(
3243
[T3_SERVER_TOKEN_ENV]: token,
3344
[T3_THREAD_ID_ENV]: session.threadId,
3445
...(options?.cliShimPath ? { [T3_CLI_ENV]: options.cliShimPath } : {}),
46+
...(options?.cliEntryPath ? { [T3_CLI_ENTRY_ENV]: options.cliEntryPath } : {}),
47+
...(options?.cliEntryPath && options.cliRuntimePath
48+
? { [T3_CLI_RUNTIME_ENV]: options.cliRuntimePath }
49+
: {}),
3550
};
3651
}

‎apps/server/src/handoff/protocol.ts‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,18 @@ export const T3_THREAD_ID_ENV = "T3_THREAD_ID";
2424
* sessions where no installed `d` binary is on PATH (e.g. dev servers).
2525
*/
2626
export const T3_CLI_ENV = "T3_CLI";
27+
/**
28+
* CLI entry the shim at `T3_CLI` runs. Injected because the entry is not
29+
* always reachable from the shim's own directory: a packaged desktop app
30+
* unpacks the plugin but keeps the server bundle inside its asar archive.
31+
*/
32+
export const T3_CLI_ENTRY_ENV = "T3_CLI_ENTRY";
33+
/**
34+
* Executable the shim reads `T3_CLI_ENTRY` with — this server's own runtime,
35+
* so an archived entry is read by the same asar-aware Electron binary that
36+
* runs the server.
37+
*/
38+
export const T3_CLI_RUNTIME_ENV = "T3_CLI_RUNTIME";
2739

2840
export const HANDOFF_HTTP_PATH = "/handoff";
2941

Lines changed: 39 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,39 @@
1+
import * as NodeServices from "@effect/platform-node/NodeServices";
2+
import { assert, it } from "@effect/vitest";
3+
import * as Effect from "effect/Effect";
4+
5+
import { asarUnpackedTwin, resolveT3ClaudePluginLocation } from "./ClaudePlugin.ts";
6+
7+
it("redirects a path inside an asar archive to its unpacked twin", () => {
8+
assert.equal(
9+
asarUnpackedTwin(
10+
"/Applications/T3.app/Contents/Resources/app.asar/apps/server/dist/claude-plugin",
11+
),
12+
"/Applications/T3.app/Contents/Resources/app.asar.unpacked/apps/server/dist/claude-plugin",
13+
);
14+
// Windows sidecar, backslash separators.
15+
assert.equal(
16+
asarUnpackedTwin(
17+
"C:\\Program Files\\T3\\resources\\server.asar\\apps\\server\\dist\\claude-plugin",
18+
),
19+
"C:\\Program Files\\T3\\resources\\server.asar.unpacked\\apps\\server\\dist\\claude-plugin",
20+
);
21+
});
22+
23+
it("leaves paths outside an archive alone", () => {
24+
assert.equal(asarUnpackedTwin("/repo/apps/server/claude-plugin"), undefined);
25+
// A directory merely named `*.asar` with nothing below it is not a prefix.
26+
assert.equal(asarUnpackedTwin("/repo/app.asar"), undefined);
27+
});
28+
29+
it.layer(NodeServices.layer)("resolveT3ClaudePluginLocation", (it) => {
30+
it.effect("resolves the source-layout plugin and its CLI entry", () =>
31+
Effect.gen(function* () {
32+
const location = yield* resolveT3ClaudePluginLocation();
33+
34+
assert.isDefined(location);
35+
assert.isTrue(location.pluginDir.endsWith("apps/server/claude-plugin"));
36+
assert.isTrue(location.cliEntryPath?.endsWith("apps/server/src/bin.ts"));
37+
}),
38+
);
39+
});

‎apps/server/src/provider/Drivers/ClaudePlugin.ts‎

Lines changed: 79 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -13,16 +13,56 @@ import * as Path from "effect/Path";
1313
/** Plugin name as declared in `.claude-plugin/plugin.json`. */
1414
export const T3_CLAUDE_PLUGIN_NAME = "t3";
1515

16+
/** Where the shipped plugin lives, and how its `bin/t3` shim reaches this server's CLI. */
17+
export interface T3ClaudePluginLocation {
18+
/**
19+
* Directory handed to the SDK `plugins` option and scanned for the skill
20+
* list. Never a path inside an asar archive: `claude` is a plain subprocess
21+
* and cannot read one, so an archived plugin loads nowhere.
22+
*/
23+
readonly pluginDir: string;
24+
/**
25+
* Server CLI entry the plugin's `bin/t3` shim execs. Resolved next to the
26+
* running bundle, so in a packaged app it stays inside the archive — the
27+
* shim runs it through this process's own executable, which is asar-aware
28+
* when that executable is Electron.
29+
*/
30+
readonly cliEntryPath?: string;
31+
}
32+
33+
/**
34+
* `…/app.asar/rest` → `…/app.asar.unpacked/rest`, or undefined when the path
35+
* is not inside an archive. Covers both the desktop `app.asar` and the Windows
36+
* `server.asar` sidecar.
37+
*/
38+
export const asarUnpackedTwin = (candidate: string): string | undefined => {
39+
const match = /\.asar[/\\]/.exec(candidate);
40+
if (!match) {
41+
return undefined;
42+
}
43+
const boundary = match.index + ".asar".length;
44+
return `${candidate.slice(0, boundary)}.unpacked${candidate.slice(boundary)}`;
45+
};
46+
47+
/** CLI entry points, relative to the plugin directory: source layout, then bundled. */
48+
const CLI_ENTRY_CANDIDATES = ["../src/bin.ts", "../bin.mjs"] as const;
49+
1650
/**
17-
* Resolve the shipped plugin directory. Mirrors `resolveStaticDir`: prefer a
18-
* bundled copy next to the built entry, fall back to the monorepo source
19-
* layout, and return `undefined` when neither exists so a missing plugin
20-
* never blocks session start.
51+
* Resolve the shipped plugin. Mirrors `resolveStaticDir`: prefer a bundled copy
52+
* next to the built entry, fall back to the monorepo source layout, and return
53+
* `undefined` when the plugin is unusable so a missing plugin never blocks
54+
* session start.
2155
*/
22-
export const resolveT3ClaudePluginDir = Effect.fn("resolveT3ClaudePluginDir")(
23-
function* (): Effect.fn.Return<string | undefined, never, FileSystem.FileSystem | Path.Path> {
56+
export const resolveT3ClaudePluginLocation = Effect.fn("resolveT3ClaudePluginLocation")(
57+
function* (): Effect.fn.Return<
58+
T3ClaudePluginLocation | undefined,
59+
never,
60+
FileSystem.FileSystem | Path.Path
61+
> {
2462
const path = yield* Path.Path;
2563
const fileSystem = yield* FileSystem.FileSystem;
64+
const exists = (target: string) =>
65+
fileSystem.exists(target).pipe(Effect.orElseSucceed(() => false));
2666

2767
const candidates = [
2868
// Bundled layout: dist/claude-plugin next to dist/bin.mjs.
@@ -32,12 +72,40 @@ export const resolveT3ClaudePluginDir = Effect.fn("resolveT3ClaudePluginDir")(
3272
];
3373

3474
for (const candidate of candidates) {
35-
const manifestExists = yield* fileSystem
36-
.exists(path.join(candidate, ".claude-plugin", "plugin.json"))
37-
.pipe(Effect.orElseSucceed(() => false));
38-
if (manifestExists) {
39-
return candidate;
75+
const manifestPath = path.join(candidate, ".claude-plugin", "plugin.json");
76+
if (!(yield* exists(manifestPath))) {
77+
continue;
4078
}
79+
80+
// In a packaged app this candidate resolves through Electron's
81+
// asar-aware fs, so it exists for us but not for the `claude`
82+
// subprocess. Only the unpacked twin is a real directory; without it
83+
// the plugin would load nowhere while still showing up in the picker.
84+
const unpackedCandidate = asarUnpackedTwin(candidate);
85+
if (unpackedCandidate !== undefined) {
86+
if (!(yield* exists(path.join(unpackedCandidate, ".claude-plugin", "plugin.json")))) {
87+
yield* Effect.logWarning(
88+
`[claude] t3 plugin at ${candidate} is packed inside an asar archive and was not unpacked — t3:handoff is unavailable.`,
89+
);
90+
return undefined;
91+
}
92+
}
93+
94+
// Resolved from the archived candidate rather than the twin: only
95+
// claude-plugin is unpacked, the server bundle itself stays packed.
96+
let cliEntryPath: string | undefined;
97+
for (const relativeEntry of CLI_ENTRY_CANDIDATES) {
98+
const entry = path.resolve(path.join(candidate, relativeEntry));
99+
if (yield* exists(entry)) {
100+
cliEntryPath = entry;
101+
break;
102+
}
103+
}
104+
105+
return {
106+
pluginDir: unpackedCandidate ?? candidate,
107+
...(cliEntryPath ? { cliEntryPath } : {}),
108+
};
41109
}
42110
return undefined;
43111
},

‎apps/server/src/provider/Drivers/ClaudeSkills.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -99,7 +99,7 @@ export const discoverClaudeSkills = Effect.fn("discoverClaudeSkills")(function*
9999
environment?: NodeJS.ProcessEnv,
100100
options?: {
101101
/**
102-
* Directory of the T3-shipped Claude plugin (see `resolveT3ClaudePluginDir`).
102+
* Directory of the T3-shipped Claude plugin (see `resolveT3ClaudePluginLocation`).
103103
* Its skills are injected into every session via the SDK `plugins` option
104104
* and addressed plugin-qualified (`t3:<skill>`), so they never collide
105105
* with user/project skills. Passed explicitly by the caller so discovery

‎apps/server/src/provider/Layers/ClaudeAdapter.ts‎

Lines changed: 14 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@ import {
2121
type ModelUsage,
2222
} from "@anthropic-ai/claude-agent-sdk";
2323
import { parseCliArgs } from "@t3tools/shared/cliArgs";
24+
import { HostProcessExecutablePath } from "@t3tools/shared/hostProcess";
2425
import {
2526
ApprovalRequestId,
2627
type CanonicalItemType,
@@ -82,7 +83,7 @@ import { makeHandoffCallbackEnvironment } from "../../handoff/callbackEnvironmen
8283
import * as McpProviderSession from "../../mcp/McpProviderSession.ts";
8384
import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
8485
import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
85-
import { resolveT3ClaudePluginDir } from "../Drivers/ClaudePlugin.ts";
86+
import { resolveT3ClaudePluginLocation } from "../Drivers/ClaudePlugin.ts";
8687
import {
8788
getClaudeModelCapabilities,
8889
isClaudeUltracodeEffort,
@@ -1708,10 +1709,12 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
17081709
claudeSettings.binaryPath,
17091710
claudeEnvironment,
17101711
);
1711-
const t3ClaudePluginDir = yield* resolveT3ClaudePluginDir().pipe(
1712+
const t3ClaudePlugin = yield* resolveT3ClaudePluginLocation().pipe(
17121713
Effect.provideService(Path.Path, path),
17131714
Effect.provideService(FileSystem.FileSystem, fileSystem),
17141715
);
1716+
const t3ClaudePluginDir = t3ClaudePlugin?.pluginDir;
1717+
const hostExecutablePath = yield* HostProcessExecutablePath;
17151718
const nativeEventLogger =
17161719
options?.nativeEventLogger ??
17171720
(options?.nativeEventLogPath !== undefined
@@ -4318,7 +4321,15 @@ export const makeClaudeAdapter = Effect.fn("makeClaudeAdapter")(function* (
43184321
? {
43194322
...claudeEnvironment,
43204323
...makeHandoffCallbackEnvironment(mcpSession, {
4321-
...(t3ClaudePluginDir ? { cliShimPath: path.join(t3ClaudePluginDir, "bin", "t3") } : {}),
4324+
...(t3ClaudePluginDir
4325+
? { cliShimPath: path.join(t3ClaudePluginDir, "bin", "t3") }
4326+
: {}),
4327+
...(t3ClaudePlugin?.cliEntryPath
4328+
? {
4329+
cliEntryPath: t3ClaudePlugin.cliEntryPath,
4330+
cliRuntimePath: hostExecutablePath,
4331+
}
4332+
: {}),
43224333
}),
43234334
}
43244335
: claudeEnvironment;

‎apps/server/src/provider/Layers/ClaudeProvider.ts‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ import {
4141
} from "../providerSnapshot.ts";
4242
import { resolveClaudeSdkExecutablePath } from "../Drivers/ClaudeExecutable.ts";
4343
import { makeClaudeEnvironment } from "../Drivers/ClaudeHome.ts";
44-
import { resolveT3ClaudePluginDir } from "../Drivers/ClaudePlugin.ts";
44+
import { resolveT3ClaudePluginLocation } from "../Drivers/ClaudePlugin.ts";
4545
import { discoverClaudeSkills } from "../Drivers/ClaudeSkills.ts";
4646

4747
const DEFAULT_CLAUDE_MODEL_CAPABILITIES: ModelCapabilities = createModelCapabilities({
@@ -921,7 +921,8 @@ export const checkClaudeProviderStatus = Effect.fn("checkClaudeProviderStatus")(
921921
const capabilities = resolveCapabilities
922922
? yield* resolveCapabilities(claudeSettings).pipe(Effect.orElseSucceed(() => undefined))
923923
: undefined;
924-
const t3PluginDir = yield* resolveT3ClaudePluginDir();
924+
const t3Plugin = yield* resolveT3ClaudePluginLocation();
925+
const t3PluginDir = t3Plugin?.pluginDir;
925926
const skills = yield* discoverClaudeSkills(claudeSettings, cwd, resolvedEnvironment, {
926927
...(t3PluginDir ? { t3PluginDir } : {}),
927928
});

0 commit comments

Comments
 (0)