Files
waggle-os/packages/shared/src/tool-detection.ts
shumeiko.it 80db300485 refactor(shared): drop the headless task contract from tool manifests
The `task` spec (argv templates, access modes, output dialects) and the
capability flags headlessTask, structuredProgress, resumable and
liveWaggleDance described how a Waggle Room run drove a coding agent
without its UI. Nothing runs tools headless any more, so built-in
manifests, the third-party adapter loader and detection results no
longer carry them. An adapter file that still declares `task` is
rejected like any other unknown key.
2026-11-01 11:08:26 +01:00

177 lines
6.2 KiB
TypeScript

/**
* Tool Detection — shared types for AI-OS Phase 0.
*
* Mission: report which external AI tools are installed on the user's
* machine, with version. Foundation for the launcher dock (Phase 2) and the
* Mission Control inventory tile (Phase 4).
*
* The detection itself runs in the sidecar (agent package); these types
* live in @waggle/shared so both the sidecar and the web bundle can
* consume the same envelope without duplicating shapes.
*
* Out of scope for these types:
* - Tool spawn / process management (Phase 2)
* - Workspace context injection (Phase 2)
*/
/**
* Canonical built-in AI-tool execution surfaces. CLI and desktop surfaces use
* distinct ids whenever they have different launch/task capabilities.
*/
export const SUPPORTED_TOOLS = [
'claude-code',
'claude-desktop',
'cursor',
'codex',
'codex-desktop',
'hermes',
'hermes-desktop',
'openclaw',
] as const;
export type ToolId = typeof SUPPORTED_TOOLS[number];
/**
* AI-OS #5 — how a tool is detected. `path` = PATH lookup by binary name (CLI
* tools; the only kind a third-party JSON adapter may declare). `candidates` =
* platform-branching candidate-path probe, resolved by built-in agent code
* (GUI/desktop apps) — not expressible declaratively, so built-in only.
*/
export type ToolDetectSpec =
| { kind: 'path'; binaryName: string }
| { kind: 'candidates' };
export type ToolReleaseStatus = 'supported' | 'roadmap';
/**
* AI-OS #5 — declarative descriptor for one external tool. The single source of
* truth for the per-tool facts that used to be duplicated across SUPPORTED_TOOLS
* / LAUNCH_COHORT / TOOL_DISPLAY_NAMES / the per-tool detectors. Built-ins live in BUILTIN_TOOL_MANIFESTS; third-party
* adapters are loaded (data-only) from ~/.waggle/adapters/*.json.
*/
export interface ToolManifest {
id: string;
displayName: string;
/** Omitted means supported; roadmap integrations remain detectable but inert. */
releaseStatus?: ToolReleaseStatus;
launchable: boolean;
detect: ToolDetectSpec;
/**
* Declarative inline-prompt arg template for THIRD-PARTY path adapters
* (e.g. ['--print', '{prompt}']). Built-ins keep their logic in
* launcher-prompt-args.ts. Captured in v1; application is a fast-follow.
*/
promptArgTemplate?: string[];
/** true = first-party built-in; false/absent = loaded third-party. */
builtin?: boolean;
}
/**
* The canonical 8 built-in execution surfaces — the source of truth for their
* per-tool data.
* SUPPORTED_TOOLS (above) stays the `as const` type anchor; the cohort and
* name consts derive from these manifests.
*/
export const BUILTIN_TOOL_MANIFESTS: readonly ToolManifest[] = [
{
id: 'claude-code', displayName: 'Claude Code', launchable: true,
detect: { kind: 'path', binaryName: 'claude' }, builtin: true,
},
{
id: 'claude-desktop', displayName: 'Claude Desktop', launchable: true,
detect: { kind: 'candidates' }, builtin: true,
},
{
id: 'cursor', displayName: 'Cursor', releaseStatus: 'roadmap', launchable: false,
detect: { kind: 'candidates' }, builtin: true,
},
{
id: 'codex', displayName: 'Codex CLI', launchable: true,
detect: { kind: 'path', binaryName: 'codex' }, builtin: true,
},
{
id: 'codex-desktop', displayName: 'Codex Desktop', launchable: true,
detect: { kind: 'candidates' }, builtin: true,
},
{
id: 'hermes', displayName: 'Hermes Agent CLI', launchable: true,
detect: { kind: 'path', binaryName: 'hermes' }, builtin: true,
},
{
id: 'hermes-desktop', displayName: 'Hermes Desktop', launchable: true,
detect: { kind: 'candidates' }, builtin: true,
},
{
id: 'openclaw', displayName: 'OpenClaw', releaseStatus: 'roadmap', launchable: false,
detect: { kind: 'path', binaryName: 'openclaw' }, builtin: true,
},
] as const;
/**
* Tools the launcher dock supports end-to-end.
*
* Registered integrations can remain detectable for compatibility while
* `releaseStatus: 'roadmap'` keeps them out of the launch cohort.
*/
export const LAUNCH_COHORT: readonly ToolId[] =
BUILTIN_TOOL_MANIFESTS.filter((m) => m.launchable).map((m) => m.id as ToolId);
/**
* AI-OS #5 — apply a third-party adapter's `promptArgTemplate` to a prompt by
* substituting every `{prompt}` placeholder in each entry. Built-ins use their
* own promptArgsForTool (web); this is the declarative form for loaded adapters.
*/
export function applyPromptArgTemplate(template: readonly string[], prompt: string): string[] {
return template.map((a) => a.split('{prompt}').join(prompt));
}
/**
* Per-tool human-readable display name. Centralized so the launcher
* UI and sidecar logs agree.
*/
export const TOOL_DISPLAY_NAMES = Object.fromEntries(
BUILTIN_TOOL_MANIFESTS.map((m) => [m.id, m.displayName]),
) as Record<ToolId, string>;
/**
* Result of detecting a single tool on the user's machine.
*
* Field semantics:
* - `installed` : true iff the binary was found at a known path.
* - `installedPath` : absolute path to the binary, or null.
* - `version` : version string (best-effort; null if exec failed).
* - `diagnostic` : optional human-readable reason for any
* partial-failure case (e.g. "claude-code installed but --version
* returned non-zero").
*/
export interface DetectedTool {
/** Tool id — a built-in ToolId or a loaded third-party adapter id (#5). */
id: string;
displayName: string;
/** Release qualification inherited from the manifest. Omitted means supported. */
releaseStatus?: ToolReleaseStatus;
/** True when the tool manifest allows launching from the dock. */
launchable?: boolean;
/** True for built-in execution surfaces; false for loaded adapters. */
builtin?: boolean;
/** True when the manifest can accept the launch prompt inline. */
acceptsInlinePrompt?: boolean;
installed: boolean;
installedPath: string | null;
version: string | null;
diagnostic?: string;
}
/**
* Top-level detection envelope. Stable shape across all callers
* (sidecar route, web UI, Tauri command).
*/
export interface ToolDetectionResult {
/** Platform the detection ran on. */
platform: NodeJS.Platform | 'other';
/** ISO timestamp at which the detection completed. */
detectedAt: string;
/** Per-tool detection result. Registry order: built-ins first, then adapters. */
tools: DetectedTool[];
}