expandai 0.0.2 → 0.0.4

package/src/Hook/Claude.ts

@@ -68,7 +68,7 @@ export class ClaudeHook extends Effect.Service<ClaudeHook>()('@expandai/cli/Hook
 					hookSpecificOutput: {
 						hookEventName: 'PreToolUse',
 						permissionDecision: 'deny',
-						permissionDecisionReason: `Fetched via expand.ai — page markdown injected as additionalContext.`,
+						permissionDecisionReason: `Fetched by expand.ai instead — the captured page follows, with evidence ids for citing it. Do not retry this URL.`,
 						additionalContext: withSnapshotNote(result.markdown, result.meta.snapshotId, result.meta.playground),
 					},
 				}

package/src/Hook/SnapshotNote.ts

@@ -1,18 +1,66 @@
 import { String } from 'effect'
 
 /**
- * Prepends a short note to fetched markdown carrying the snapshot handle and the public
- * playground link, and telling the agent how to search the already-captured page by handle
- * (rather than fetching the URL again) and cite specific passages back to the user. Both the
- * Claude Code and OpenCode hooks inject this so the surfaced guidance stays identical.
+ * Prepends a short note to fetched markdown carrying the snapshot handle, the public
+ * playground link, and the citation contract. Both the Claude Code and OpenCode hooks
+ * inject this so the surfaced guidance stays identical.
+ *
+ * The citation rules are stated here rather than only in the onboarding guide or
+ * `SKILL.md`: the guide is read once during setup, and a skill may not be loaded in the
+ * session that happens to fetch. This note is the only instruction guaranteed to be in
+ * context at the moment the page arrives, so an answer that cites nothing — or cites the
+ * bare capture URL, which is not auditable — traces back to what is written here.
  */
+const FRONT_MATTER_PLAYGROUND = /^playground:\s*"?([^"\n]+)"?\s*$/mu
+
+/**
+ * Citation guidance for `expandai fetch` text output consumed by an agent. The plain
+ * command is a third fetch path alongside the hook and the MCP tools — an agent that
+ * shells out to it used to receive evidence ids with nothing telling it to cite them,
+ * and answered uncited. Humans at a TTY do not need this, so callers gate on that.
+ *
+ * Returns the markdown unchanged when no playground URL is present, rather than
+ * emitting an instruction the reader cannot follow.
+ */
+export function withCitationFooter(markdown: string): string {
+	const playgroundUrl = FRONT_MATTER_PLAYGROUND.exec(markdown)?.[1]?.trim()
+	if (playgroundUrl === undefined || playgroundUrl.length === 0) return markdown
+	const footer = String.stripMargin(`
+		|---
+		|
+		|> Cite what you take from this page. Evidence ids are stamped next to the text they
+		|> belong to, written as \`{1199}\`. End your answer with:
+		|>
+		|> **Sources**
+		|> [1] [<page title>](${playgroundUrl}?id=<evidence id>)
+		|>
+		|> One marker per sentence, numbered in order. Never invent an evidence id, and never
+		|> reuse an id from different text. A link without \`?id=\` is not a citation, so if the
+		|> sentence you want carries no id, quote one that does or say the capture has none —
+		|> never fall back to linking the original page.`)
+	return `${markdown.trimEnd()}\n\n${footer}\n`
+}
+
 export function withSnapshotNote(markdown: string, snapshotId: string, playgroundUrl: string): string {
 	const note = String.stripMargin(`
-		|> Fetched via expand.ai (snapshot \`${snapshotId}\`). View or share this capture at
-		|> ${playgroundUrl}
+		|> Fetched via expand.ai (snapshot \`${snapshotId}\`). Capture: ${playgroundUrl}
+		|>
+		|> Cite every claim you take from this page. The body below stamps an evidence id next
+		|> to the text it belongs to, written as \`{1199}\`. For each sentence you use, take the
+		|> id nearest that text and end your answer with:
+		|>
+		|> **Sources**
+		|> [1] [<page title>](${playgroundUrl}?id=<evidence id>)
+		|>
+		|> Number the markers \`[1]\`, \`[2]\`, … in the order they appear, one per sentence.
+		|> Never invent an evidence id, and never reuse an id from different text.
+		|> A bare capture link without \`?id=\` is not a citation — the reader cannot
+		|> check the sentence against the page. If the sentence you want carries no id, quote
+		|> one that does, or say the capture has none. Never fall back to the original page URL.
+		|>
 		|> To extract specific passages, search the snapshot by handle — call the \`fetch_search\`
 		|> tool with \`snapshotId: "${snapshotId}"\`, or run \`expandai search ${snapshotId} "<query>"\`.
-		|> Each snippet returns a \`citationUrl\` you can hand the user to audit the exact source.
+		|> Each snippet returns a \`citationUrl\` that already carries the right \`?id=\`.
 		|> Do not fetch this URL again.`)
 	return `${note}\n\n---\n\n${markdown}`
 }

package/src/Init/ClaudeAdapter.ts

@@ -0,0 +1,191 @@
+import { Command, CommandExecutor } from '@effect/platform'
+import { NodeCommandExecutor } from '@effect/platform-node'
+import { Config, Effect, Layer, Schema, Stream } from 'effect'
+import { CLI_VERSION } from '../Version.js'
+import { CLAUDE_PROFILE_VERSION, ClaudeProfile, type ClaudeProfileInspection } from './ClaudeProfile.js'
+import type { InitScope } from './Domain.js'
+import { HarnessConfigurationError, type HarnessInspection, HarnessInspectionError } from './HarnessAdapter.js'
+import { MutationTransaction } from './MutationTransaction.js'
+
+export class IncompatibleClaudeProfileVersionError extends Schema.TaggedError<IncompatibleClaudeProfileVersionError>()(
+	'IncompatibleClaudeProfileVersionError',
+	{
+		executingVersion: Schema.String,
+		requiredVersion: Schema.String,
+	},
+) {
+	get message() {
+		return `Executing CLI ${this.executingVersion} is incompatible with Claude profile ${this.requiredVersion}`
+	}
+}
+
+export class ClaudeProfilePolicyBlockedError extends Schema.TaggedError<ClaudeProfilePolicyBlockedError>()(
+	'ClaudeProfilePolicyBlockedError',
+	{
+		policyBlock: Schema.String,
+	},
+) {
+	get message() {
+		return `Claude Code policy blocks profile configuration: ${this.policyBlock}`
+	}
+}
+
+export class ClaudeAdapterOperationError extends Schema.TaggedError<ClaudeAdapterOperationError>()(
+	'ClaudeAdapterOperationError',
+	{
+		code: Schema.Literal('inspection_failed', 'configuration_failed'),
+	},
+) {
+	get message() {
+		return this.code === 'inspection_failed'
+			? 'Claude Code profile inspection failed'
+			: 'Claude Code profile configuration failed'
+	}
+}
+
+const PORTABLE_PROBE_TIMEOUT = '5 seconds'
+
+interface ClaudeRuntimeProbeContract {
+	readonly executingVersion: string
+	readonly portableCommandAvailable: Effect.Effect<boolean, unknown>
+}
+
+const makeClaudeRuntimeProbe = Effect.gen(function* () {
+	const commandExecutor = yield* CommandExecutor.CommandExecutor
+	const searchPath = yield* Config.string('PATH').pipe(Config.withDefault(''))
+	const portableCommandAvailable = Effect.scoped(
+		Effect.gen(function* () {
+			const command = Command.make('expandai', '--version').pipe(
+				// Version probing must not persist telemetry state or emit a request in
+				// the child. Keep the remaining environment intact while making PATH
+				// injectable for fixture verification.
+				Command.env({ ...process.env, EXPANDAI_NO_TELEMETRY: '1', PATH: searchPath }),
+				Command.stdout('pipe'),
+				Command.stderr('pipe'),
+			)
+			const child = yield* commandExecutor.start(command)
+			const [stdout, , exitCode] = yield* Effect.all(
+				[child.stdout.pipe(Stream.decodeText(), Stream.mkString), child.stderr.pipe(Stream.runDrain), child.exitCode],
+				{ concurrency: 'unbounded' },
+			)
+			return exitCode === 0 && stdout.trim() === CLI_VERSION
+		}),
+	).pipe(
+		// A shim on PATH that never exits would otherwise hang setup forever. This
+		// probe only decides a "restart your harness" hint, so a slow answer is
+		// worth no more than a missing one. `Effect.scoped` above reaps the child.
+		Effect.timeoutFail({
+			duration: PORTABLE_PROBE_TIMEOUT,
+			onTimeout: () => new Error('expandai --version timed out'),
+		}),
+		Effect.orElseSucceed(() => false),
+	)
+	return { executingVersion: CLI_VERSION, portableCommandAvailable } satisfies ClaudeRuntimeProbeContract
+})
+
+/** Runtime facts kept separate from persisted harness commands. */
+export class ClaudeRuntimeProbe extends Effect.Service<ClaudeRuntimeProbe>()('@expandai/cli/Init/ClaudeRuntimeProbe', {
+	dependencies: [NodeCommandExecutor.layer],
+	effect: makeClaudeRuntimeProbe,
+}) {
+	/**
+	 * Not `DefaultWithoutDependencies`: that layer always reports `CLI_VERSION` and
+	 * always runs the real command probe. Tests need to pin an arbitrary executing
+	 * version and a precomputed probe result, which only a fixture layer can supply.
+	 */
+	static testLayer(options: { readonly executingVersion: string; readonly portableCommandAvailable: boolean }) {
+		return Layer.succeed(
+			ClaudeRuntimeProbe,
+			ClaudeRuntimeProbe.make({
+				executingVersion: options.executingVersion,
+				portableCommandAvailable: Effect.succeed(options.portableCommandAvailable),
+			}),
+		)
+	}
+}
+
+function projectInspection(
+	inspection: ClaudeProfileInspection,
+	portableCommandAvailable: boolean,
+	changed: boolean,
+): HarnessInspection {
+	const policyBlock = inspection.policyBlocks[0]
+	const blocked = policyBlock !== undefined
+	const reloadRequired = inspection.configured && !portableCommandAvailable
+	return {
+		configured: inspection.configured,
+		changed,
+		components: inspection.components,
+		integrationVersion: inspection.profileVersion,
+		...(policyBlock === undefined ? {} : { policyBlock }),
+		runtimeState: blocked ? 'blocked' : reloadRequired ? 'reload_required' : 'unverified',
+		nextAction: blocked
+			? 'resolve-claude-policy-block'
+			: reloadRequired
+				? 'restart-claude-code-current-path-unavailable'
+				: inspection.configured
+					? 'invoke-native-webfetch'
+					: 'configure-claude-code',
+	}
+}
+
+const makeClaudeAdapter = Effect.gen(function* () {
+	const profile = yield* ClaudeProfile
+	const transaction = yield* MutationTransaction
+	const runtime = yield* ClaudeRuntimeProbe
+
+	const inspect = Effect.fn('ClaudeAdapter.inspect')(function* (scope: InitScope) {
+		return yield* Effect.gen(function* () {
+			const inspection = yield* profile.inspect(scope)
+			const portableCommandAvailable = yield* runtime.portableCommandAvailable
+			return projectInspection(inspection, portableCommandAvailable, false)
+		}).pipe(
+			Effect.catchAllDefect(() => new ClaudeAdapterOperationError({ code: 'inspection_failed' })),
+			Effect.mapError(
+				() =>
+					new HarnessInspectionError({
+						harness: 'claude-code',
+						scope,
+						error: new ClaudeAdapterOperationError({ code: 'inspection_failed' }),
+					}),
+			),
+		)
+	})
+
+	const configure = Effect.fn('ClaudeAdapter.configure')(function* (scope: InitScope) {
+		return yield* Effect.gen(function* () {
+			if (runtime.executingVersion !== CLAUDE_PROFILE_VERSION) {
+				return yield* new IncompatibleClaudeProfileVersionError({
+					executingVersion: runtime.executingVersion,
+					requiredVersion: CLAUDE_PROFILE_VERSION,
+				})
+			}
+			const portableCommandAvailable = yield* runtime.portableCommandAvailable
+			const plan = yield* profile.plan(scope)
+			const policyBlock = plan.inspection.policyBlocks[0]
+			if (policyBlock !== undefined) return yield* new ClaudeProfilePolicyBlockedError({ policyBlock })
+			yield* transaction.run(plan.operations)
+			return projectInspection(plan.resultInspection, portableCommandAvailable, plan.changed)
+		}).pipe(
+			Effect.catchAllDefect(() => new ClaudeAdapterOperationError({ code: 'configuration_failed' })),
+			Effect.mapError(
+				(error) =>
+					new HarnessConfigurationError({
+						harness: 'claude-code',
+						scope,
+						error:
+							error instanceof IncompatibleClaudeProfileVersionError || error instanceof ClaudeProfilePolicyBlockedError
+								? error
+								: new ClaudeAdapterOperationError({ code: 'configuration_failed' }),
+					}),
+			),
+		)
+	})
+
+	return { harness: 'claude-code' as const, inspect, configure } as const
+})
+
+export class ClaudeAdapter extends Effect.Service<ClaudeAdapter>()('@expandai/cli/Init/ClaudeAdapter', {
+	dependencies: [ClaudeProfile.Default, MutationTransaction.Default, ClaudeRuntimeProbe.Default],
+	effect: makeClaudeAdapter,
+}) {}