@meistrari/agent-core 0.2.0-experimental.1 → 0.2.0-experimental.3

package/src/agents/claude/claude-selected-repository-instructions.ts

@@ -0,0 +1,91 @@
+import type { HookCallbackMatcher, HookEvent, HookInput } from '@anthropic-ai/claude-agent-sdk'
+import { mkdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { AgentProviderRuntimeError } from '../agent-runtime-error'
+import { reconcileSelectedRepositoryInstructions, repositoryInstructionsUnavailable, selectedRepositoryInstructions } from '../selected-repository-instructions'
+
+// A project rule, not a CLAUDE.md: Claude Code 2.1.280 turns its AGENTS.md fallback off for every
+// nested repository once a CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md exists at the cwd.
+const managedRulePath = ['.claude', 'rules', 'coding-agent-selected-repositories.md'] as const
+
+/**
+ * The Claude counterpart of Codex's managed AGENTS.override.md. Claude Code 2.1.280 (verified by
+ * claude-selected-repository-instructions.cli.spec.ts) loads an unconditional `.claude/rules/*.md`
+ * once per process into the first user message, never the cached system block, and on resume
+ * appends the changed copy itself. It does not re-read instruction files mid-session, so a
+ * repository added to a live run rewrites the file (for later resumes and compactions) and hands
+ * the new text to the main thread as hook context at its next tool boundary or submitted prompt.
+ */
+export class ClaudeSelectedRepositoryInstructions {
+    private pendingUpdate: string | undefined
+
+    private constructor(private readonly path: string, private readonly sharedContext: string | undefined) {}
+
+    static async open(input: { cwd: string, repositoryRoots: readonly string[], sharedContext?: string }): Promise<ClaudeSelectedRepositoryInstructions> {
+        const instructions = new ClaudeSelectedRepositoryInstructions(join(input.cwd, ...managedRulePath), input.sharedContext)
+        await instructions.publish(input.repositoryRoots)
+        return instructions
+    }
+
+    async update(repositoryRoots: readonly string[]): Promise<void> {
+        await this.publish(repositoryRoots)
+        // A later update supersedes one the model has not received yet.
+        this.pendingUpdate = [
+            'The selected repositories for this session changed. These selected-repository instructions replace the earlier ones:',
+            '',
+            selectedRepositoryInstructions({ provider: 'claude', repositoryRoots, sharedContext: this.sharedContext }) ?? '',
+        ].join('\n')
+    }
+
+    hooks(): Partial<Record<HookEvent, HookCallbackMatcher[]>> {
+        // Subagent hooks carry `agent_id`; only the main thread receives the update.
+        const take = (input: HookInput): string | undefined => {
+            if (input.agent_id !== undefined)
+                return undefined
+            const text = this.pendingUpdate
+            this.pendingUpdate = undefined
+            return text
+        }
+        return {
+            PostToolUse: [{
+                hooks: [async (input) => {
+                    const text = take(input)
+                    return text ? { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } } : {}
+                }],
+            }],
+            PostToolUseFailure: [{
+                hooks: [async (input) => {
+                    const text = take(input)
+                    return text ? { hookSpecificOutput: { hookEventName: 'PostToolUseFailure', additionalContext: text } } : {}
+                }],
+            }],
+            UserPromptSubmit: [{
+                hooks: [async (input) => {
+                    const text = take(input)
+                    return text ? { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text } } : {}
+                }],
+            }],
+        }
+    }
+
+    private async publish(repositoryRoots: readonly string[]): Promise<void> {
+        // Without content the reconcile only removes a stale managed rule; no directory is created.
+        if (selectedRepositoryInstructions({ provider: 'claude', repositoryRoots, sharedContext: this.sharedContext }) === undefined) {
+            await reconcileSelectedRepositoryInstructions({ provider: 'claude', path: this.path, repositoryRoots })
+            return
+        }
+        try {
+            await mkdir(dirname(this.path), { recursive: true, mode: 0o750 })
+        }
+        catch (error) {
+            const cause = new AgentProviderRuntimeError({
+                message: 'Failed to create the Claude project rules directory.',
+                details: { instructionBridgePath: this.path },
+                retryable: true,
+                cause: error,
+            })
+            throw repositoryInstructionsUnavailable({ recoveryKind: 'retry', cause })
+        }
+        await reconcileSelectedRepositoryInstructions({ provider: 'claude', path: this.path, repositoryRoots, sharedContext: this.sharedContext })
+    }
+}

package/src/agents/claude/claude-skill-catalog.ts

@@ -0,0 +1,75 @@
+import type { SlashCommand } from '@anthropic-ai/claude-agent-sdk'
+import type { AgentSkill } from '../../protocol'
+import type { AgentEventDraft } from '../agent-event-stream'
+import { createHash } from 'node:crypto'
+
+type SessionSkillsUpdatedDraft = Extract<AgentEventDraft, { type: 'session.skills.updated' }>
+
+/**
+ * Builds the canonical `session.skills.updated` snapshot for Claude from the CLI's own command list
+ * (initialize response, `reloadPlugins`, and `system/commands_changed`), the Claude counterpart of
+ * `CodexSkillCatalog`. Only skills from the plugins this adapter installs are listed; Claude Code's
+ * built-in commands are not skills. Claude names plugin skills `<plugin>:<skill>` but also accepts
+ * the plain `<skill>` alias, so the catalog reports the plain name and `/<skill>` from the web
+ * composer invokes the same skill for both providers.
+ *
+ * Snapshots are held until the run's `system/init` validation publishes its lifecycle events, so a
+ * catalog never precedes `session.started`.
+ */
+export class ClaudeSkillCatalog {
+    private ready = false
+    private pending: AgentSkill[] | undefined
+    private lastSnapshot: string | undefined
+
+    constructor(private readonly input: {
+        pluginScopes: ReadonlyMap<string, AgentSkill['scope']>
+        emit: (draft: SessionSkillsUpdatedDraft) => void
+    }) {}
+
+    publish(commands: readonly SlashCommand[]): void {
+        const skills = claudeSkillsFromCommands(commands, this.input.pluginScopes)
+        if (!this.ready) {
+            this.pending = skills
+            return
+        }
+        this.emitIfChanged(skills)
+    }
+
+    markReady(): void {
+        this.ready = true
+        const pending = this.pending
+        this.pending = undefined
+        if (pending)
+            this.emitIfChanged(pending)
+    }
+
+    private emitIfChanged(skills: AgentSkill[]): void {
+        const snapshot = JSON.stringify(skills)
+        if (snapshot === this.lastSnapshot)
+            return
+        this.lastSnapshot = snapshot
+        this.input.emit({ type: 'session.skills.updated', payload: { skills } })
+    }
+}
+
+export function claudeSkillsFromCommands(commands: readonly SlashCommand[], pluginScopes: ReadonlyMap<string, AgentSkill['scope']>): AgentSkill[] {
+    return commands.flatMap((command) => {
+        // `builtin` is reported by SDK 0.3.280 and later; older runtimes list only non-builtin skills here.
+        if ('builtin' in command && command.builtin === true)
+            return []
+        const separator = command.name.indexOf(':')
+        const plugin = separator > 0 ? command.name.slice(0, separator) : undefined
+        const scope = plugin === undefined ? undefined : pluginScopes.get(plugin)
+        if (plugin === undefined || scope === undefined)
+            return []
+        const aliases = command.aliases ?? []
+        const name = aliases.find(alias => !alias.includes(':')) ?? command.name.slice(separator + 1)
+        const description = command.description.replace(`(${plugin}) `, '').trim() || name
+        return [{ id: skillId([command.name, ...aliases]), name, description, scope }]
+    })
+}
+
+function skillId(names: readonly string[]): string {
+    const digest = createHash('sha256').update(`claude-skill\0${names.join('\0')}`).digest('hex')
+    return `skill_${digest}`
+}

package/src/agents/claude/claude-steered-notifications.ts

@@ -0,0 +1,180 @@
+import type { HookCallbackMatcher, HookEvent, HookInput } from '@anthropic-ai/claude-agent-sdk'
+import { Buffer } from 'node:buffer'
+import { randomUUID } from 'node:crypto'
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join } from 'node:path'
+import z from 'zod'
+import { AgentNotificationStoreError } from '../agent-runtime-error'
+
+const storeDirectoryName = 'coding-agent-notifications'
+const storeFileName = 'steered-notifications.json'
+// Bounds the redrive-dedupe memory; a redrive arrives within the same command's retry window.
+const deliveredCommandIdLimit = 200
+
+const pendingSteeredNotificationSchema = z.strictObject({
+    commandId: z.string().min(1),
+    turnId: z.string().min(1),
+    text: z.string().min(1),
+    queuedAt: z.string().datetime(),
+})
+
+const steeredNotificationStoreFileSchema = z.strictObject({
+    version: z.literal(1),
+    sessionId: z.string().min(1),
+    pending: z.array(pendingSteeredNotificationSchema),
+    delivered: z.array(z.strictObject({ commandId: z.string().min(1), turnId: z.string().min(1) })),
+})
+
+type PendingSteeredNotification = z.infer<typeof pendingSteeredNotificationSchema>
+type StoreFile = z.infer<typeof steeredNotificationStoreFileSchema>
+
+export type SteeredNotificationEnqueueResult
+    = | { kind: 'queued' }
+        | { kind: 'duplicate', turnId: string }
+
+/** Envelopes taken from the store together, and the one text that hands them to Claude. */
+export interface SteeredNotificationDelivery {
+    readonly text: string
+    readonly notifications: readonly PendingSteeredNotification[]
+}
+
+/**
+ * Notifications accepted into an active Claude turn wait here, in sandbox-local session state
+ * beside the user-input store, until a hook delivers them to the model. The receipt is returned
+ * only after the envelope is on disk, and an envelope leaves the store only when a hook hands it
+ * to Claude Code, so a process restart or session resume re-delivers what was accepted but not yet
+ * delivered, and a redriven command id that was already accepted is never queued twice.
+ */
+export class ClaudeSteeredNotificationStore {
+    private constructor(private readonly filePath: string, private file: StoreFile) {}
+
+    static open(input: { sessionId: string, transcriptPath: string }): ClaudeSteeredNotificationStore {
+        const filePath = join(
+            dirname(input.transcriptPath),
+            storeDirectoryName,
+            Buffer.from(input.sessionId, 'utf8').toString('base64url'),
+            storeFileName,
+        )
+        return new ClaudeSteeredNotificationStore(filePath, readStoreFile({ filePath, sessionId: input.sessionId }))
+    }
+
+    hasPending(): boolean {
+        return this.file.pending.length > 0
+    }
+
+    enqueue(notification: Omit<PendingSteeredNotification, 'queuedAt'>): SteeredNotificationEnqueueResult {
+        const known = this.file.pending.find(entry => entry.commandId === notification.commandId)
+            ?? this.file.delivered.find(entry => entry.commandId === notification.commandId)
+        if (known)
+            return { kind: 'duplicate', turnId: known.turnId }
+        this.write({ ...this.file, pending: [...this.file.pending, { ...notification, queuedAt: new Date().toISOString() }] })
+        return { kind: 'queued' }
+    }
+
+    /** Hands every pending envelope to the caller and records them as delivered in one write. */
+    takePending(): SteeredNotificationDelivery | undefined {
+        const pending = this.file.pending
+        if (pending.length === 0)
+            return undefined
+        const delivered = [...this.file.delivered, ...pending.map(entry => ({ commandId: entry.commandId, turnId: entry.turnId }))]
+        this.write({ ...this.file, pending: [], delivered: delivered.slice(-deliveredCommandIdLimit) })
+        return { text: pending.map(entry => entry.text).join('\n\n'), notifications: pending }
+    }
+
+    /** Returns taken envelopes that Claude provably never received to the front of the queue. */
+    restore(delivery: SteeredNotificationDelivery): void {
+        const commandIds = new Set(delivery.notifications.map(entry => entry.commandId))
+        this.write({
+            ...this.file,
+            pending: [...delivery.notifications, ...this.file.pending.filter(entry => !commandIds.has(entry.commandId))],
+            delivered: this.file.delivered.filter(entry => !commandIds.has(entry.commandId)),
+        })
+    }
+
+    private write(file: StoreFile): void {
+        const parent = dirname(this.filePath)
+        const tempPath = join(parent, `.${basename(this.filePath)}.${process.pid}.${randomUUID()}.tmp`)
+        try {
+            mkdirSync(parent, { recursive: true, mode: 0o700 })
+            writeFileSync(tempPath, `${JSON.stringify(file)}\n`, { encoding: 'utf8', mode: 0o600 })
+            renameSync(tempPath, this.filePath)
+        }
+        catch (error) {
+            throw new AgentNotificationStoreError({
+                message: `Failed to persist steered notifications for session ${file.sessionId}.`,
+                details: { sessionId: file.sessionId },
+                cause: error,
+            })
+        }
+        this.file = file
+    }
+}
+
+function readStoreFile(input: { filePath: string, sessionId: string }): StoreFile {
+    let raw: string
+    try {
+        raw = readFileSync(input.filePath, 'utf8')
+    }
+    catch (error) {
+        if (error instanceof Error && 'code' in error && error.code === 'ENOENT')
+            return { version: 1, sessionId: input.sessionId, pending: [], delivered: [] }
+        throw new AgentNotificationStoreError({ message: `Failed to read steered notifications for session ${input.sessionId}.`, details: { sessionId: input.sessionId }, cause: error })
+    }
+    let json: unknown
+    try {
+        json = JSON.parse(raw)
+    }
+    catch (error) {
+        throw new AgentNotificationStoreError({ message: `Steered notifications for session ${input.sessionId} are not valid JSON.`, details: { sessionId: input.sessionId }, cause: error })
+    }
+    const parsed = steeredNotificationStoreFileSchema.safeParse(json)
+    if (!parsed.success || parsed.data.sessionId !== input.sessionId)
+        throw new AgentNotificationStoreError({ message: `Steered notifications for session ${input.sessionId} are invalid.`, details: { sessionId: input.sessionId } })
+    return parsed.data
+}
+
+/**
+ * Delivers pending steered notifications inside the current main turn (verified on Claude Code
+ * 2.1.280): the next main-thread tool boundary gets them as PostToolUse(Failure) additional
+ * context, and a turn that tries to end first is continued by a Stop-hook block whose reason is the
+ * envelope. An interrupted or failed turn fires neither, so the next submitted input receives them
+ * as UserPromptSubmit context, which also covers envelopes recovered after a restart or resume.
+ * A notify that lands after the Stop hook passed is delivered by the run's follow-up turn (see
+ * ClaudeRun). Subagent hooks carry `agent_id` and never consume them, and neither does the
+ * synthetic `/compact` input: compaction is not a turn the model answers.
+ */
+export function claudeSteeredNotificationHooks(store: ClaudeSteeredNotificationStore): Partial<Record<HookEvent, HookCallbackMatcher[]>> {
+    const take = (input: HookInput): string | undefined => input.agent_id === undefined && !isCompactCommand(input) ? store.takePending()?.text : undefined
+    return {
+        PostToolUse: [{
+            hooks: [async (input) => {
+                const text = take(input)
+                return text ? { hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: text } } : {}
+            }],
+        }],
+        PostToolUseFailure: [{
+            hooks: [async (input) => {
+                const text = take(input)
+                return text ? { hookSpecificOutput: { hookEventName: 'PostToolUseFailure', additionalContext: text } } : {}
+            }],
+        }],
+        Stop: [{
+            hooks: [async (input) => {
+                const text = take(input)
+                return text ? { decision: 'block', reason: text } : {}
+            }],
+        }],
+        UserPromptSubmit: [{
+            hooks: [async (input) => {
+                const text = take(input)
+                return text ? { hookSpecificOutput: { hookEventName: 'UserPromptSubmit', additionalContext: text } } : {}
+            }],
+        }],
+    }
+}
+
+// CLI 2.1.280 runs no UserPromptSubmit hook for the synthetic `/compact` input (live-probed); this
+// keeps envelopes for a real prompt if a later runtime starts to.
+function isCompactCommand(input: HookInput): boolean {
+    return input.hook_event_name === 'UserPromptSubmit' && /^\/compact(?:\s|$)/u.test(input.prompt.trimStart())
+}

package/src/agents/claude/claude-tool-mapper.ts

@@ -1,7 +1,7 @@
-import type { Options } from '@anthropic-ai/claude-agent-sdk'
+import type { Options, PostToolUseFailureHookInput, PostToolUseHookInput } from '@anthropic-ai/claude-agent-sdk'
 import type { AgentRunMetadata, AgentUserInputQuestion, JsonValue } from '../../protocol'
 import type { AgentTool } from '../agent-tool'
-import { tool as claudeTool, createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk'
+import { tool as claudeTool, createSdkMcpServer, HOOK_EVENTS } from '@anthropic-ai/claude-agent-sdk'
 import { isAppError } from '../../errors'
 import { AgentProviderProtocolError } from '../agent-runtime-error'
 import { agentToolActorDenialMessage, agentToolAllowsActor } from '../agent-tool'
@@ -12,6 +12,15 @@ export const CLAUDE_CODE_TOOL_USE_ID_META_KEY = 'claudecode/toolUseId'
 
 const UNEXPECTED_TOOL_FAILURE_MESSAGE = 'The tool could not be executed.'
 
+export type ClaudeNativeToolActor = Readonly<{ kind: 'main' }> | Readonly<{ kind: 'subagent', id: string }>
+
+type ClaudeNativeToolActorHooksInput = Readonly<{
+    expectedSessionId: string
+    toolNames: readonly string[]
+    register: (input: { toolName: string, toolUseId: string, actor: ClaudeNativeToolActor, signal: AbortSignal }) => Promise<void>
+    finish: (input: { toolUseId: string }) => Promise<void>
+}>
+
 interface ClaudeMcpToolExtra {
     _meta?: {
         [CLAUDE_CODE_TOOL_USE_ID_META_KEY]?: unknown
@@ -113,6 +122,76 @@ export function claudeAllowedToolNames(tools: readonly AgentTool[]): string[] {
     return tools.map(runtimeTool => claudeToolName(runtimeTool.name))
 }
 
+export function claudeNativeToolActorHooks(input: ClaudeNativeToolActorHooksInput): NonNullable<Options['hooks']> {
+    const toolNames = new Set(input.toolNames)
+    const denial = () => ({
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse' as const,
+            permissionDecision: 'deny' as const,
+            permissionDecisionReason: 'The native tool caller could not be attributed.',
+        },
+    })
+    const finish = async (hookInput: PostToolUseHookInput): Promise<Record<string, never>> => {
+        if (hookInput.hook_event_name !== 'PostToolUse' || !toolNames.has(hookInput.tool_name))
+            return {}
+        try {
+            await input.finish({ toolUseId: hookInput.tool_use_id })
+        }
+        catch {
+            // The registration is already unusable after the native call; cleanup cannot rewrite its result.
+        }
+        return {}
+    }
+    const finishFailure = async (hookInput: PostToolUseFailureHookInput): Promise<Record<string, never>> => {
+        if (hookInput.hook_event_name !== 'PostToolUseFailure' || !toolNames.has(hookInput.tool_name))
+            return {}
+        try {
+            await input.finish({ toolUseId: hookInput.tool_use_id })
+        }
+        catch {
+            // The failed native call already has its outcome; cleanup remains best effort.
+        }
+        return {}
+    }
+
+    return {
+        PreToolUse: [{
+            hooks: [async (hookInput, toolUseId, options) => {
+                if (hookInput.hook_event_name !== 'PreToolUse' || !toolNames.has(hookInput.tool_name))
+                    return {}
+                if (hookInput.session_id !== input.expectedSessionId || toolUseId !== hookInput.tool_use_id)
+                    return denial()
+                const actor: ClaudeNativeToolActor = hookInput.agent_id === undefined
+                    ? { kind: 'main' }
+                    : { kind: 'subagent', id: hookInput.agent_id }
+                try {
+                    await input.register({ toolName: hookInput.tool_name, toolUseId: hookInput.tool_use_id, actor, signal: options.signal })
+                    return {}
+                }
+                catch {
+                    return denial()
+                }
+            }],
+        }],
+        PostToolUse: [{ hooks: [async (hookInput, _toolUseId, _options) => hookInput.hook_event_name === 'PostToolUse'
+            ? await finish(hookInput)
+            : {}] }],
+        PostToolUseFailure: [{ hooks: [async (hookInput, _toolUseId, _options) => hookInput.hook_event_name === 'PostToolUseFailure'
+            ? await finishFailure(hookInput)
+            : {}] }],
+    }
+}
+
+export function mergeClaudeToolHooks(...hooks: Array<Options['hooks']>): Options['hooks'] {
+    const merged: NonNullable<Options['hooks']> = {}
+    for (const event of HOOK_EVENTS) {
+        const matchers = hooks.flatMap(value => value?.[event] ?? [])
+        if (matchers.length > 0)
+            merged[event] = matchers
+    }
+    return Object.keys(merged).length > 0 ? merged : undefined
+}
+
 export function claudeToolActorHooks(tools: readonly AgentTool[]): Options['hooks'] {
     const toolsByName = new Map(
         tools

package/src/agents/claude/claude-workspace-skills.ts

@@ -0,0 +1,87 @@
+import { mkdir, readdir, readlink, rm, stat, symlink, unlink, writeFile } from 'node:fs/promises'
+import { basename, join } from 'node:path'
+import { stableRepositoryRoots } from '../codex/codex-skill-roots'
+
+/** Plugin name of the generated per-run workspace skills plugin; Claude lists its skills as `workspace:<name>`. */
+export const claudeWorkspaceSkillsPluginName = 'workspace'
+
+/**
+ * Claude Code does not read `<repository>/.agents/skills`, and a plugin's `skills` directory is read
+ * exactly one level deep. Each run therefore owns a generated local plugin whose `skills` directory
+ * holds one symlink per repository skill, the Claude counterpart of Codex `skills/extraRoots/set`.
+ * The first repository (in sorted root order) keeps a skill's own directory name; a later
+ * repository's same-named skill gets a `<repository>--<skill>` link, so both stay listed, as in the
+ * Codex catalog, and `/<skill>` resolves to the first.
+ */
+export class ClaudeWorkspaceSkills {
+    private constructor(readonly pluginPath: string) {}
+
+    static async create(pluginPath: string): Promise<ClaudeWorkspaceSkills> {
+        await mkdir(join(pluginPath, '.claude-plugin'), { recursive: true, mode: 0o700 })
+        await mkdir(join(pluginPath, 'skills'), { recursive: true, mode: 0o700 })
+        await writeFile(join(pluginPath, '.claude-plugin', 'plugin.json'), `${JSON.stringify({
+            name: claudeWorkspaceSkillsPluginName,
+            description: 'Skills from the session\'s workspace repositories (.agents/skills).',
+        })}\n`)
+        return new ClaudeWorkspaceSkills(pluginPath)
+    }
+
+    /** Links the current skills of every repository root; returns whether the linked set changed. */
+    async sync(repositoryRoots: readonly string[]): Promise<boolean> {
+        const skillsDirectory = join(this.pluginPath, 'skills')
+        const desired = await desiredSkillLinks(repositoryRoots)
+        let changed = false
+        for (const entry of await readdir(skillsDirectory)) {
+            const linkPath = join(skillsDirectory, entry)
+            const target = desired.get(entry)
+            if (target !== undefined && await readlink(linkPath).catch(() => undefined) === target)
+                continue
+            await unlink(linkPath)
+            changed = true
+        }
+        for (const [name, target] of desired) {
+            const linkPath = join(skillsDirectory, name)
+            if (await readlink(linkPath).catch(() => undefined) === target)
+                continue
+            await symlink(target, linkPath)
+            changed = true
+        }
+        return changed
+    }
+
+    async remove(): Promise<void> {
+        await rm(this.pluginPath, { recursive: true, force: true })
+    }
+}
+
+async function desiredSkillLinks(repositoryRoots: readonly string[]): Promise<Map<string, string>> {
+    const links = new Map<string, string>()
+    for (const root of stableRepositoryRoots(repositoryRoots)) {
+        const skillsRoot = join(root, '.agents', 'skills')
+        for (const skill of await skillDirectories(skillsRoot)) {
+            const target = join(skillsRoot, skill)
+            let name = skill
+            for (let suffix = 1; links.has(name); suffix += 1)
+                name = suffix === 1 ? `${linkSegment(basename(root))}--${skill}` : `${linkSegment(basename(root))}--${skill}-${suffix}`
+            links.set(name, target)
+        }
+    }
+    return links
+}
+
+async function skillDirectories(skillsRoot: string): Promise<string[]> {
+    const entries = await readdir(skillsRoot, { withFileTypes: true }).catch(() => [])
+    const skills: string[] = []
+    for (const entry of entries) {
+        if (entry.name.startsWith('.') || !(entry.isDirectory() || entry.isSymbolicLink()))
+            continue
+        const manifest = await stat(join(skillsRoot, entry.name, 'SKILL.md')).catch(() => undefined)
+        if (manifest?.isFile())
+            skills.push(entry.name)
+    }
+    return skills.sort()
+}
+
+function linkSegment(value: string): string {
+    return value.replaceAll(/[^\w.-]/gu, '-') || 'repository'
+}

package/src/agents/claude/index.ts

@@ -1 +1,3 @@
+export * from './claude-auth'
+export * from './claude-desktop'
 export * from './claude-provider'

package/src/agents/codex/codex-auth-mapper.ts

@@ -0,0 +1,27 @@
+import type { CodexAuthRefreshInput, CodexAuthTokens } from './codex-auth'
+import type { ClientRequestParamsByMethod, CodexChatGPTAuthTokensRefreshParams, CodexChatGPTAuthTokensRefreshResponse } from './codex-protocol'
+
+export function toCodexLoginParams(tokens: CodexAuthTokens): ClientRequestParamsByMethod['account/login/start'] {
+    return {
+        type: 'chatgptAuthTokens',
+        accessToken: tokens.accessToken,
+        chatgptAccountId: tokens.chatgptAccountId,
+        chatgptPlanType: tokens.chatgptPlanType ?? null,
+    }
+}
+
+export function toAuthRefreshInput(params: CodexChatGPTAuthTokensRefreshParams, tokens: CodexAuthTokens): CodexAuthRefreshInput {
+    return {
+        reason: params.reason,
+        rejectedTokenGeneration: tokens.accessTokenGeneration,
+        rejectedTokenFingerprint: tokens.accessTokenFingerprint,
+    }
+}
+
+export function toCodexRefreshResponse(tokens: CodexAuthTokens): CodexChatGPTAuthTokensRefreshResponse {
+    return {
+        accessToken: tokens.accessToken,
+        chatgptAccountId: tokens.chatgptAccountId,
+        chatgptPlanType: tokens.chatgptPlanType ?? null,
+    }
+}

package/src/agents/codex/codex-auth.ts

@@ -1,3 +1,8 @@
+import { Buffer } from 'node:buffer'
+import { z } from 'zod'
+
+const tokenExpirySchema = z.object({ exp: z.number().finite() })
+
 export interface CodexAuthTokens {
     accessToken: string
     accessTokenGeneration: number
@@ -43,3 +48,17 @@ export type CodexAuthentication
     = | { kind: 'chatgpt', provider: CodexAuthProvider }
         | { kind: 'api-key', provider: CodexApiKeyAuthProvider, modelProvider?: string }
         | { kind: 'amazon-bedrock', region: string, provider: CodexBedrockAuthProvider }
+/** Expiry scheduling hint only; this neither authenticates nor verifies a JWT signature. */
+export function codexAuthTokensExpireSoon(tokens: CodexAuthTokens): boolean {
+    const parts = tokens.accessToken.split('.')
+    if (parts.length !== 3 || !parts[1])
+        return false
+    try {
+        const payload = tokenExpirySchema.safeParse(JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8')))
+        return payload.success && payload.data.exp <= Date.now() / 1000 + 60
+    }
+    catch {
+        // Opaque or non-JWT credentials retain native/explicit refresh; invent no expiry.
+        return false
+    }
+}