expandai 0.0.2 → 0.0.3

package/src/Init/ClaudeProfile.ts

@@ -0,0 +1,496 @@
+import { homedir } from 'node:os'
+import { FileSystem, Path } from '@effect/platform'
+import { NodeFileSystem, NodePath } from '@effect/platform-node'
+import { Array, Config, Effect, Either, Layer, Option, Schema } from 'effect'
+import {
+	hookCommandFor,
+	isExpandaiHookCommand,
+	planClaudeHook,
+	planClaudeWebFetchDeny,
+	SettingsSchema,
+	WEBFETCH_MATCHER,
+} from '../Install/Claude/Hook.js'
+import { planClaudeMcp } from '../Install/Claude/Mcp.js'
+import { planClaudeSkill, SKILL_FILE_NAME, SKILL_NAME } from '../Install/Claude/Skill.js'
+import { type CliCommand, CliInvocation, McpServersConfigSchema, SERVER_KEY } from '../Install/Domain.js'
+import { CLI_VERSION } from '../Version.js'
+import type { InitComponent, InitScope } from './Domain.js'
+import type { MutationExpectedState, MutationOperation } from './MutationTransaction.js'
+
+export const CLAUDE_PROFILE_VERSION = CLI_VERSION
+
+export const CLAUDE_POLICY_MANAGED_HOOKS = 'managed_hooks_only'
+export const CLAUDE_POLICY_MANAGED_MCP = 'managed_mcp_only'
+export const CLAUDE_POLICY_MCP_DENIED = 'managed_mcp_denied'
+export const CLAUDE_POLICY_MCP_NOT_ALLOWED = 'managed_mcp_not_allowed'
+export const CLAUDE_POLICY_READ_ONLY = 'target_read_only'
+
+interface ClaudeTargetLocations {
+	readonly settingsFile: string
+	readonly skillDirectory: string
+	readonly skillFile: string
+	readonly mcpFile: string
+	readonly managedSettingsFiles: string[]
+	readonly managedSettingsDirectories: string[]
+}
+
+export interface ClaudeManagedSettingsLocationSet {
+	readonly files: string[]
+	readonly directories: string[]
+}
+
+interface ClaudeRegistrationInspection {
+	readonly current: boolean
+	readonly installed: boolean
+	readonly legacyVariants: string[]
+	readonly version?: string
+}
+
+export interface ClaudeProfileInspection {
+	readonly scope: InitScope
+	readonly targets: ClaudeTargetLocations
+	readonly hook: ClaudeRegistrationInspection
+	readonly skill: ClaudeRegistrationInspection
+	readonly mcp: ClaudeRegistrationInspection
+	readonly components: InitComponent[]
+	readonly configured: boolean
+	readonly profileVersion: string
+	readonly componentVersions: {
+		readonly hook?: string
+		readonly skill?: string
+		readonly mcp?: string
+	}
+	readonly policyBlocks: string[]
+	readonly remotePolicyMayApply: true
+	readonly reloadMayBeRequired: boolean
+	readonly consentMayBeRequired: boolean
+}
+
+export interface ClaudeProfileMutationPlan {
+	readonly changed: boolean
+	readonly inspection: ClaudeProfileInspection
+	readonly resultInspection: ClaudeProfileInspection
+	readonly operations: MutationOperation[]
+}
+
+interface LoadedClaudeProfile {
+	readonly targets: ClaudeTargetLocations
+	readonly settings: typeof SettingsSchema.Type
+	readonly settingsExpected: MutationExpectedState
+	readonly settingsText?: string
+	readonly skillExpected: MutationExpectedState
+	readonly skillText?: string
+	readonly bundledSkillText: string
+	readonly mcp: typeof McpServersConfigSchema.Type
+	readonly mcpExpected: MutationExpectedState
+	readonly mcpText?: string
+	readonly managedSettings: ReadonlyArray<Record<string, unknown>>
+	readonly readOnlyTargets: string[]
+}
+
+const JsonRecord = Schema.parseJson(Schema.Record({ key: Schema.String, value: Schema.Unknown }))
+const PROFILE_VERSION_PATTERN = /^\s*expandai-profile-version:\s*([^\s]+)\s*$/mu
+const textEncoder = new TextEncoder()
+const textDecoder = new TextDecoder()
+const MODE_MAX = 0o7777
+
+function isUnknownRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function defaultManagedSettingsLocations(): ClaudeManagedSettingsLocationSet {
+	if (process.platform === 'darwin') {
+		const root = '/Library/Application Support/ClaudeCode'
+		return {
+			files: [`${root}/managed-settings.json`, `${root}/managed-mcp.json`],
+			directories: [`${root}/managed-settings.d`],
+		}
+	}
+	if (process.platform === 'win32') {
+		const root = 'C:\\Program Files\\ClaudeCode'
+		return {
+			files: [`${root}\\managed-settings.json`, `${root}\\managed-mcp.json`],
+			directories: [`${root}\\managed-settings.d`],
+		}
+	}
+	return {
+		files: ['/etc/claude-code/managed-settings.json', '/etc/claude-code/managed-mcp.json'],
+		directories: ['/etc/claude-code/managed-settings.d'],
+	}
+}
+
+/** Discoverable file-based Claude managed-policy locations for the current platform. */
+export class ClaudeManagedSettingsLocations extends Effect.Service<ClaudeManagedSettingsLocations>()(
+	'@expandai/cli/Init/ClaudeManagedSettingsLocations',
+	{
+		sync: defaultManagedSettingsLocations,
+	},
+) {
+	static testLayer(locations: ClaudeManagedSettingsLocationSet) {
+		return Layer.succeed(ClaudeManagedSettingsLocations, ClaudeManagedSettingsLocations.make(locations))
+	}
+}
+
+function listContainsExpandai(value: unknown): boolean {
+	if (!Array.isArray(value)) return false
+	return value.some((entry) => {
+		if (entry === SERVER_KEY) return true
+		if (!isUnknownRecord(entry)) return false
+		return entry.name === SERVER_KEY || entry.serverName === SERVER_KEY
+	})
+}
+
+function managedPolicyBlocks(settings: ReadonlyArray<Record<string, unknown>>): string[] {
+	const blocks = new Set<string>()
+	const managedMcpOnly = settings.some((value) => value.allowManagedMcpServersOnly === true)
+	const allowedMcpConfigured = settings.some((value) => Array.isArray(value.allowedMcpServers))
+	const expandaiAllowed = settings.some((value) => listContainsExpandai(value.allowedMcpServers))
+	for (const value of settings) {
+		if (value.allowManagedHooksOnly === true) blocks.add(CLAUDE_POLICY_MANAGED_HOOKS)
+		if (listContainsExpandai(value.deniedMcpServers)) blocks.add(CLAUDE_POLICY_MCP_DENIED)
+	}
+	if (managedMcpOnly && !expandaiAllowed) blocks.add(CLAUDE_POLICY_MANAGED_MCP)
+	if (allowedMcpConfigured && !expandaiAllowed) blocks.add(CLAUDE_POLICY_MCP_NOT_ALLOWED)
+	return [...blocks].sort()
+}
+
+function skillVersion(text: string | undefined): string | undefined {
+	if (text === undefined) return undefined
+	return PROFILE_VERSION_PATTERN.exec(text)?.[1]
+}
+
+function mcpLegacyVariant(value: unknown): string[] {
+	if (!isUnknownRecord(value)) return value === undefined ? [] : ['owned-entry']
+	const command = value.command
+	const args = value.args
+	if (command === 'npx' && Array.isArray(args) && args[0] === '-y') return ['npx-y']
+	if (typeof command === 'string' && command !== 'expandai' && /(?:^|[\\/])expandai(?:\.exe)?$/u.test(command)) {
+		return ['absolute-path']
+	}
+	return ['owned-entry']
+}
+
+function hookLegacyVariant(command: string): string {
+	if (/^npx\s+-y\s+/u.test(command.trim())) return 'npx-y'
+	if (/\shook\s+claude\s*$/u.test(command)) return 'old-command-spelling'
+	if (/^(?:"|'|\/|[A-Za-z]:\\)/u.test(command.trim())) return 'absolute-path'
+	if (/^if\s+command\s+-v\s+expandai/u.test(command.trim())) return 'npx-shell-fallback'
+	return 'unversioned'
+}
+
+function makeInspection(scope: InitScope, loaded: LoadedClaudeProfile, cli: CliCommand): ClaudeProfileInspection {
+	const hookPlan = planClaudeHook(loaded.settings, CLAUDE_PROFILE_VERSION, cli)
+	const denyPlan = planClaudeWebFetchDeny(hookPlan.settings)
+	const hookEntries = (loaded.settings.hooks.PreToolUse ?? []).flatMap((entry) =>
+		entry.hooks.filter((hook) => isExpandaiHookCommand(hook.command)).map((hook) => ({ entry, hook })),
+	)
+	const hookVersion = hookEntries.length === 1 ? hookEntries[0]?.hook.expandaiProfileVersion : undefined
+	const hookCurrent = !hookPlan.changed && !denyPlan.changed
+	const hookLegacy = hookCurrent
+		? []
+		: hookEntries.map(({ entry, hook }) =>
+				entry.matcher === WEBFETCH_MATCHER && hook.command === hookCommandFor(cli)
+					? 'unversioned'
+					: hookLegacyVariant(hook.command),
+			)
+
+	const plannedSkill = planClaudeSkill(loaded.skillText, loaded.bundledSkillText, CLAUDE_PROFILE_VERSION)
+	const currentSkillVersion = skillVersion(loaded.skillText)
+	const skillCurrent = loaded.skillText !== undefined && !plannedSkill.changed
+
+	const mcpValue = loaded.mcp.mcpServers[SERVER_KEY]
+	const mcpCurrent = !planClaudeMcp(loaded.mcp, cli).changed
+	const components: InitComponent[] = []
+	if (hookCurrent) components.push('webfetch-hook')
+	if (skillCurrent) components.push('runtime-skill')
+	if (mcpCurrent) components.push('mcp')
+
+	const policyBlocks = managedPolicyBlocks(loaded.managedSettings)
+	if (loaded.readOnlyTargets.length > 0) policyBlocks.push(CLAUDE_POLICY_READ_ONLY)
+
+	return {
+		scope,
+		targets: loaded.targets,
+		hook: {
+			current: hookCurrent,
+			installed: hookEntries.length > 0,
+			legacyVariants: hookLegacy,
+			...(hookVersion === undefined ? {} : { version: hookVersion }),
+		},
+		skill: {
+			current: skillCurrent,
+			installed: loaded.skillText !== undefined,
+			legacyVariants: loaded.skillText === undefined || skillCurrent ? [] : ['outdated-runtime-skill'],
+			...(currentSkillVersion === undefined ? {} : { version: currentSkillVersion }),
+		},
+		mcp: {
+			current: mcpCurrent,
+			installed: mcpValue !== undefined,
+			legacyVariants: mcpCurrent ? [] : mcpLegacyVariant(mcpValue),
+		},
+		components,
+		configured: components.length === 3,
+		profileVersion: CLAUDE_PROFILE_VERSION,
+		componentVersions: {
+			...(hookVersion === undefined ? {} : { hook: hookVersion }),
+			...(currentSkillVersion === undefined ? {} : { skill: currentSkillVersion }),
+			...(mcpCurrent ? { mcp: CLAUDE_PROFILE_VERSION } : {}),
+		},
+		policyBlocks: [...new Set(policyBlocks)].sort(),
+		remotePolicyMayApply: true,
+		reloadMayBeRequired: !hookCurrent || !mcpCurrent,
+		consentMayBeRequired: scope === 'project',
+	}
+}
+
+const makeClaudeProfile = Effect.gen(function* () {
+	const fileSystem = yield* FileSystem.FileSystem
+	const path = yield* Path.Path
+	const managedSettingsLocations = yield* ClaudeManagedSettingsLocations
+	// Resolved once per service: whether `expandai` is on PATH decides what the
+	// written hook and MCP entries invoke, and it cannot change mid-install.
+	const cli = yield* (yield* CliInvocation).resolve()
+	const home = yield* Config.string('HOME').pipe(Config.withDefault(homedir()))
+	const cwd = yield* Config.string('PWD').pipe(Config.withDefault(process.cwd()))
+	const moduleFile = yield* path.fromFileUrl(new URL(import.meta.url))
+	const bundledSkillFile = path.resolve(path.dirname(moduleFile), '..', '..', 'skills', SKILL_NAME, SKILL_FILE_NAME)
+
+	const readOptional = Effect.fnUntraced(function* (file: string) {
+		return (yield* fileSystem.exists(file)) ? yield* fileSystem.readFileString(file) : undefined
+	})
+
+	const readPlannedFile = Effect.fnUntraced(function* (file: string) {
+		if (!(yield* fileSystem.exists(file))) {
+			return { expected: { exists: false } as const }
+		}
+		const info = yield* fileSystem.stat(file)
+		const bytes = yield* fileSystem.readFile(file)
+		return {
+			expected: {
+				exists: true,
+				type: 'File',
+				bytes,
+				mode: info.mode & MODE_MAX,
+			} as const,
+			text: textDecoder.decode(bytes),
+		}
+	})
+
+	const expectedDirectory = Effect.fnUntraced(function* (directory: string) {
+		if (!(yield* fileSystem.exists(directory))) return { exists: false } as const
+		const info = yield* fileSystem.stat(directory)
+		if (info.type !== 'Directory') throw new Error('Planned directory target is not a directory')
+		return {
+			exists: true,
+			type: 'Directory',
+			mode: info.mode & MODE_MAX,
+		} as const
+	})
+
+	const writableAncestor = Effect.fnUntraced(function* (target: string) {
+		function ancestors(candidate: string): string[] {
+			const parent = path.dirname(candidate)
+			return parent === candidate ? [candidate] : [candidate, ...ancestors(parent)]
+		}
+		const candidates = ancestors(target)
+		const states = yield* Effect.forEach(candidates, (candidate) =>
+			fileSystem.exists(candidate).pipe(Effect.map((exists) => ({ candidate, exists }))),
+		)
+		const candidate = states.find((state) => state.exists)?.candidate ?? candidates[candidates.length - 1]
+		if (candidate === undefined) return false
+		const info = yield* fileSystem.stat(candidate)
+		return (info.mode & 0o222) !== 0
+	})
+
+	const mutationRequirementsWritable = Effect.fnUntraced(function* (operation: MutationOperation) {
+		if (
+			operation.type === 'write' &&
+			operation.expected?.exists === true &&
+			operation.expected.type === 'File' &&
+			!(yield* Effect.either(fileSystem.access(operation.path, { writable: true }))).pipe(Either.isRight)
+		) {
+			return false
+		}
+		if (operation.type === 'mkdir' && operation.expected?.exists === true) return true
+
+		const parent = path.dirname(operation.path)
+		function ancestors(candidate: string): string[] {
+			const next = path.dirname(candidate)
+			return next === candidate ? [candidate] : [candidate, ...ancestors(next)]
+		}
+		const candidates = ancestors(parent)
+		const states = yield* Effect.forEach(candidates, (candidate) =>
+			fileSystem.exists(candidate).pipe(Effect.map((exists) => ({ candidate, exists }))),
+		)
+		const nearest = states.find((state) => state.exists)?.candidate
+		if (nearest === undefined) return false
+		const existing = states.filter((state) => state.exists)
+		const traversable = yield* Effect.forEach(existing, ({ candidate }) =>
+			fileSystem.stat(candidate).pipe(
+				Effect.map((info) => info.type === 'Directory' && (process.platform === 'win32' || (info.mode & 0o111) !== 0)),
+				Effect.orElseSucceed(() => false),
+			),
+		)
+		if (!traversable.every(Boolean)) return false
+		// FileSystem.access performs the platform's effective writable check.
+		// Windows has no separate directory-traverse/ACL primitive here, so the
+		// transaction remains the final fail-closed enforcement for that facet.
+		return (yield* Effect.either(fileSystem.access(nearest, { writable: true }))).pipe(Either.isRight)
+	})
+
+	const load = Effect.fn('ClaudeProfile.load')(function* (scope: InitScope) {
+		const root = scope === 'global' ? home : cwd
+		const skillDirectory = path.join(root, '.claude', 'skills', SKILL_NAME)
+		const managed = managedSettingsLocations
+		const dropInFiles = yield* Effect.flatMap(
+			Effect.forEach(managed.directories, (directory) =>
+				fileSystem.exists(directory).pipe(
+					Effect.flatMap((exists) => (exists ? fileSystem.readDirectory(directory) : Effect.succeed([]))),
+					Effect.map((entries) =>
+						entries
+							.filter((entry) => !entry.startsWith('.') && entry.endsWith('.json'))
+							.sort()
+							.map((entry) => path.join(directory, entry)),
+					),
+				),
+			),
+			(files) => Effect.succeed(files.flat()),
+		)
+		const targets: ClaudeTargetLocations = {
+			settingsFile: path.join(root, '.claude', 'settings.json'),
+			skillDirectory,
+			skillFile: path.join(skillDirectory, SKILL_FILE_NAME),
+			mcpFile: scope === 'global' ? path.join(home, '.claude.json') : path.join(cwd, '.mcp.json'),
+			managedSettingsFiles: [...managed.files, ...dropInFiles],
+			managedSettingsDirectories: managed.directories,
+		}
+
+		const settingsFile = yield* readPlannedFile(targets.settingsFile)
+		const skillFile = yield* readPlannedFile(targets.skillFile)
+		const mcpFile = yield* readPlannedFile(targets.mcpFile)
+		const settingsText = settingsFile.text
+		const skillText = skillFile.text
+		const mcpText = mcpFile.text
+		const bundledSkillText = yield* fileSystem.readFileString(bundledSkillFile)
+		const settings = yield* Schema.decode(SettingsSchema)(settingsText ?? '{}')
+		const mcp = yield* Schema.decode(McpServersConfigSchema)(mcpText ?? '{}')
+		const managedSettings = yield* Effect.forEach(targets.managedSettingsFiles, (file) =>
+			readOptional(file).pipe(
+				Effect.flatMap((text) =>
+					text === undefined
+						? Effect.succeed(Option.none())
+						: Schema.decode(JsonRecord)(text).pipe(Effect.map(Option.some)),
+				),
+			),
+		)
+		const readOnlyTargets = yield* Effect.filter([targets.settingsFile, targets.skillFile, targets.mcpFile], (target) =>
+			writableAncestor(target).pipe(Effect.map((writable) => !writable)),
+		)
+
+		return {
+			targets,
+			settings,
+			settingsExpected: settingsFile.expected,
+			...(settingsText === undefined ? {} : { settingsText }),
+			skillExpected: skillFile.expected,
+			...(skillText === undefined ? {} : { skillText }),
+			bundledSkillText,
+			mcp,
+			mcpExpected: mcpFile.expected,
+			...(mcpText === undefined ? {} : { mcpText }),
+			managedSettings: Array.getSomes(managedSettings),
+			readOnlyTargets,
+		} satisfies LoadedClaudeProfile
+	})
+
+	const inspect = Effect.fn('ClaudeProfile.inspect')(function* (scope: InitScope) {
+		return makeInspection(scope, yield* load(scope), cli)
+	})
+
+	const plan = Effect.fn('ClaudeProfile.plan')(function* (scope: InitScope) {
+		const loaded = yield* load(scope)
+		const hookPlan = planClaudeHook(loaded.settings, CLAUDE_PROFILE_VERSION, cli)
+		// One settings file, one write: the deny rule is layered onto the hook plan's
+		// output so both land together or neither does.
+		const denyPlan = planClaudeWebFetchDeny(hookPlan.settings)
+		const settingsChanged = hookPlan.changed || denyPlan.changed
+		const skillPlan = planClaudeSkill(loaded.skillText, loaded.bundledSkillText, CLAUDE_PROFILE_VERSION)
+		const mcpPlan = planClaudeMcp(loaded.mcp, cli)
+		const settingsText = `${yield* Schema.encode(SettingsSchema)(denyPlan.settings)}\n`
+		const mcpText = `${yield* Schema.encode(McpServersConfigSchema)(mcpPlan.config)}\n`
+		const settingsDirectory = path.dirname(loaded.targets.settingsFile)
+		const skillsDirectory = path.dirname(loaded.targets.skillDirectory)
+		const operations: MutationOperation[] = []
+		if (settingsChanged || skillPlan.changed) {
+			operations.push({
+				type: 'mkdir',
+				path: settingsDirectory,
+				expected: yield* expectedDirectory(settingsDirectory),
+			})
+		}
+		if (settingsChanged) {
+			operations.push({
+				type: 'write',
+				path: loaded.targets.settingsFile,
+				bytes: textEncoder.encode(settingsText),
+				expected: loaded.settingsExpected,
+			})
+		}
+		if (skillPlan.changed) {
+			operations.push({
+				type: 'mkdir',
+				path: skillsDirectory,
+				expected: yield* expectedDirectory(skillsDirectory),
+			})
+			operations.push({
+				type: 'mkdir',
+				path: loaded.targets.skillDirectory,
+				expected: yield* expectedDirectory(loaded.targets.skillDirectory),
+			})
+			operations.push({
+				type: 'write',
+				path: loaded.targets.skillFile,
+				bytes: textEncoder.encode(skillPlan.text),
+				expected: loaded.skillExpected,
+			})
+		}
+		if (mcpPlan.changed) {
+			operations.push({
+				type: 'write',
+				path: loaded.targets.mcpFile,
+				bytes: textEncoder.encode(mcpText),
+				expected: loaded.mcpExpected,
+			})
+		}
+		const requirements = yield* Effect.forEach(operations, mutationRequirementsWritable)
+		const inspectedLoaded = requirements.every(Boolean)
+			? loaded
+			: { ...loaded, readOnlyTargets: [...loaded.readOnlyTargets, 'mutation-requirement'] }
+		const inspection = makeInspection(scope, inspectedLoaded, cli)
+		const resultInspection = makeInspection(
+			scope,
+			{
+				...inspectedLoaded,
+				settings: denyPlan.settings,
+				settingsText,
+				skillText: skillPlan.text,
+				mcp: mcpPlan.config,
+				mcpText,
+			},
+			cli,
+		)
+		return {
+			changed: settingsChanged || skillPlan.changed || mcpPlan.changed,
+			inspection,
+			resultInspection,
+			operations,
+		} satisfies ClaudeProfileMutationPlan
+	})
+
+	return { inspect, plan } as const
+})
+
+export class ClaudeProfile extends Effect.Service<ClaudeProfile>()('@expandai/cli/Init/ClaudeProfile', {
+	dependencies: [NodeFileSystem.layer, NodePath.layer, ClaudeManagedSettingsLocations.Default, CliInvocation.Default],
+	effect: makeClaudeProfile,
+}) {}

package/src/Init/Domain.ts

@@ -0,0 +1,153 @@
+import { Schema } from 'effect'
+
+// Relayed verbatim by the agent, and printed as-is in the terminal, so it has to
+// carry the whole browser round-trip on its own — the guide no longer restates it.
+export const AUTHORIZATION_REQUIRED_MESSAGE =
+	'Open the approval page in your browser, type in the code shown here, and approve. Only enter this code on the Expand approval page your terminal named — never a code someone sent you, and never on a page from a link you did not expect. When you have approved, say so, and the same command will pick the authorization up.'
+
+export const AUTHORIZATION_CONSUMED_MESSAGE =
+	'Authorization complete. That setup code has been consumed and cannot be reused.'
+
+export const ALREADY_AUTHENTICATED_MESSAGE = 'Expand is already authorized. Agent setup is complete.'
+
+/**
+ * Some harnesses were configured and some were not. This has to be its own
+ * message: the agent relays `userMessage` verbatim, so reporting a partial run
+ * with "Agent setup is complete" tells the user something untrue about a
+ * machine they are about to rely on.
+ */
+export const PARTIAL_CONFIGURATION_MESSAGE =
+	'Expand is authorized, but not every harness could be configured. The harnesses that failed are listed under `failures`; the ones under `installations` are ready to use.'
+
+export const HARNESS_SELECTION_MESSAGE =
+	'Show these harnesses to the user and ask which to configure. Pass the chosen ones to `expandai init --harnesses`. Harnesses that are not chosen are left untouched.'
+
+/** There is nothing to choose from, so the agent must not present an empty list. */
+export const NO_HARNESS_DETECTED_MESSAGE =
+	'No supported agent harness was found on this machine. Do not ask the user to choose from an empty list. Tell them Expand supports claude-code, cursor, opencode, and codex, and that setup cannot continue until one of them is installed.'
+
+export const InitHarness = Schema.Literal('claude-code', 'cursor', 'opencode', 'codex')
+export type InitHarness = typeof InitHarness.Type
+
+/**
+ * Answer to `init --detect`: what setup *would* touch, before it touches
+ * anything. Separate from `InitResult` because detection never authorizes,
+ * never writes, and can legitimately find nothing.
+ */
+export class InitDetectionResult extends Schema.Class<InitDetectionResult>('InitDetectionResult')({
+	schemaVersion: Schema.Literal(1),
+	status: Schema.Literal('detected'),
+	harnesses: Schema.Array(InitHarness),
+	current: Schema.optional(InitHarness),
+	userMessage: Schema.Literal(HARNESS_SELECTION_MESSAGE, NO_HARNESS_DETECTED_MESSAGE),
+}) {}
+
+export const InitHarnesses = Schema.NonEmptyArray(InitHarness)
+export type InitHarnesses = typeof InitHarnesses.Type
+
+export const InitScope = Schema.Literal('project', 'global')
+export type InitScope = typeof InitScope.Type
+
+export const InitComponent = Schema.Literal('webfetch-hook', 'runtime-skill', 'mcp')
+export type InitComponent = typeof InitComponent.Type
+
+export const InitRuntimeState = Schema.Literal('unverified', 'observed', 'reload_required', 'blocked')
+export type InitRuntimeState = typeof InitRuntimeState.Type
+
+export const InitStatus = Schema.Literal('authorization_required', 'completed')
+export type InitStatus = typeof InitStatus.Type
+
+// A dashboard setup token is a pre-approved RFC 8628 device code minted by
+// better-auth: opaque, bounded, single-use.
+const SetupToken = Schema.String.pipe(Schema.minLength(20), Schema.maxLength(256))
+
+const SafeSetupToken = Schema.transform(SetupToken, Schema.Redacted(Schema.String), {
+	strict: true,
+	decode: (setupToken) => setupToken,
+	// Long enough to satisfy the base schema on re-encode; still obviously not a token.
+	encode: () => '<redacted-redacted-setup-token>',
+})
+
+export class InitRequest extends Schema.Class<InitRequest>('InitRequest')({
+	harnesses: InitHarnesses,
+	scope: InitScope,
+	setupToken: Schema.optional(SafeSetupToken),
+}) {}
+
+const InitAuthorizationRequiredResult = Schema.Struct({
+	schemaVersion: Schema.Literal(1),
+	status: Schema.Literal('authorization_required'),
+	harnesses: InitHarnesses,
+	scope: InitScope,
+	userMessage: Schema.Literal(AUTHORIZATION_REQUIRED_MESSAGE),
+	authorization: Schema.Struct({
+		url: Schema.URL,
+		// Typed by the human into the approval page. Deliberately not embedded in
+		// the URL: entering it is the one moment a phished user can notice the
+		// request is not theirs.
+		userCode: Schema.String,
+		approvalExpiresAt: Schema.DateTimeUtc,
+	}),
+})
+
+/** Whether the harness has actually loaded what we wrote, and what to do if not. */
+const InitVerification = Schema.Struct({
+	runtimeState: InitRuntimeState,
+	nextAction: Schema.String,
+})
+
+/** One harness that setup wrote to, and what it now reports about itself. */
+const InitInstallation = Schema.Struct({
+	harness: InitHarness,
+	configured: Schema.Boolean,
+	changed: Schema.Boolean,
+	components: Schema.Array(InitComponent),
+	version: Schema.String,
+	verification: InitVerification,
+})
+
+/**
+ * A harness that was attempted and did not land. Named separately because the
+ * agent is asked to tell the user *which* of their agents is not set up, and it
+ * has no other way to know: `harnesses` lists what was requested and
+ * `installations` what worked, but the difference alone says neither why nor
+ * whether retrying helps.
+ */
+const InitFailure = Schema.Struct({
+	harness: InitHarness,
+	code: Schema.String,
+	recoverable: Schema.Boolean,
+})
+
+const InitCompletedResult = Schema.Struct({
+	schemaVersion: Schema.Literal(1),
+	status: Schema.Literal('completed'),
+	harnesses: InitHarnesses,
+	scope: InitScope,
+	userMessage: Schema.Literal(
+		AUTHORIZATION_CONSUMED_MESSAGE,
+		ALREADY_AUTHENTICATED_MESSAGE,
+		PARTIAL_CONFIGURATION_MESSAGE,
+	),
+	auth: Schema.Struct({
+		healthy: Schema.Boolean,
+	}),
+	// Which project `scope: 'project'` actually meant. It resolves to the working
+	// directory, which for an agent may be anywhere — a repo, a home directory,
+	// a temp folder — and nothing else in this result says where config landed.
+	projectPath: Schema.optional(Schema.String),
+	installations: Schema.NonEmptyArray(InitInstallation),
+	// Absent when every selected harness succeeded.
+	failures: Schema.optional(Schema.Array(InitFailure)),
+})
+
+export const InitResult = Schema.Union(InitAuthorizationRequiredResult, InitCompletedResult)
+export type InitResult = typeof InitResult.Type
+
+export class InitErrorEnvelope extends Schema.Class<InitErrorEnvelope>('InitErrorEnvelope')({
+	schemaVersion: Schema.Literal(1),
+	status: Schema.Literal('error'),
+	code: Schema.String,
+	message: Schema.String,
+	recoverable: Schema.Boolean,
+}) {}

package/src/Init/HarnessAdapter.ts

@@ -0,0 +1,35 @@
+import { Inspectable, Schema } from 'effect'
+import { type InitComponent, InitHarness, type InitRuntimeState, InitScope } from './Domain.js'
+
+export interface HarnessInspection {
+	readonly configured: boolean
+	readonly changed?: boolean
+	readonly components: InitComponent[]
+	readonly integrationVersion?: string
+	readonly policyBlock?: string
+	readonly nextAction: string
+	readonly runtimeState?: InitRuntimeState
+}
+
+export class HarnessInspectionError extends Schema.TaggedError<HarnessInspectionError>()('HarnessInspectionError', {
+	harness: InitHarness,
+	scope: InitScope,
+	error: Schema.Defect,
+}) {
+	get message() {
+		return `Failed to inspect ${this.harness} (${this.scope}): ${Inspectable.format(this.error)}`
+	}
+}
+
+export class HarnessConfigurationError extends Schema.TaggedError<HarnessConfigurationError>()(
+	'HarnessConfigurationError',
+	{
+		harness: InitHarness,
+		scope: InitScope,
+		error: Schema.Defect,
+	},
+) {
+	get message() {
+		return `Failed to configure ${this.harness} (${this.scope}): ${Inspectable.format(this.error)}`
+	}
+}