tabwright 1.0.0

package/src/capability-agent-skill.ts

@@ -0,0 +1,305 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { requireCapability, type CapabilityRecord } from './capability-registry.js'
+
+export type AgentSkillTarget = 'codex'
+export type AgentSkillFileStatus = 'created' | 'updated' | 'unchanged'
+
+export interface AgentSkillFileResult {
+  relativePath: string
+  path: string
+  status: AgentSkillFileStatus
+}
+
+export interface CapabilityAgentSkillResult {
+  target: AgentSkillTarget
+  capabilityId: string
+  dir: string
+  files: AgentSkillFileResult[]
+  next: string[]
+}
+
+export interface CapabilityAgentSkillShowResult {
+  target: AgentSkillTarget
+  capabilityId: string
+  dir: string
+  files: Array<{
+    relativePath: string
+    path: string
+    content: string
+  }>
+}
+
+export interface CapabilityAgentSkillStatus {
+  target: AgentSkillTarget
+  draftExists: boolean
+  draftPath: string
+  installedExists: boolean
+  installedPath: string
+  initCommand: string
+  showCommand: string
+  installCommand: string
+}
+
+const SKILL_TEMPLATE_MARKER = '<!-- TABWRIGHT_AGENT_SKILL_TEMPLATE: edit before install -->'
+
+export function initCapabilityAgentSkill(options: {
+  id: string
+  cwd?: string
+  target?: AgentSkillTarget
+  overwrite?: boolean
+}): CapabilityAgentSkillResult {
+  const target = options.target || 'codex'
+  const capability = requireCapability({ id: options.id, cwd: options.cwd })
+  const dir = getCapabilityAgentSkillDir({ capability, target })
+  const files = [
+    writeSkillFile({
+      filePath: path.join(dir, 'SKILL.md'),
+      relativePath: 'SKILL.md',
+      content: buildCodexSkillTemplate(capability),
+      overwrite: options.overwrite,
+    }),
+    writeSkillFile({
+      filePath: path.join(dir, 'agents', 'openai.yaml'),
+      relativePath: 'agents/openai.yaml',
+      content: buildOpenAiAgentTemplate(capability),
+      overwrite: options.overwrite,
+    }),
+  ]
+  return {
+    target,
+    capabilityId: capability.manifest.id,
+    dir,
+    files,
+    next: [
+      `Edit ${path.join(dir, 'SKILL.md')} with the real usage workflow and display rules.`,
+      `tabwright capability skill install ${capability.manifest.id}`,
+    ],
+  }
+}
+
+export function installCapabilityAgentSkill(options: {
+  id: string
+  cwd?: string
+  target?: AgentSkillTarget
+  overwrite?: boolean
+  codexHome?: string
+  capability?: CapabilityRecord
+}): CapabilityAgentSkillResult {
+  const target = options.target || 'codex'
+  const capability = options.capability || requireCapability({ id: options.id, cwd: options.cwd })
+  const dir = getCapabilityAgentSkillDir({ capability, target })
+  const skillPath = path.join(dir, 'SKILL.md')
+  if (!fs.existsSync(skillPath)) {
+    throw new Error(`Agent skill draft not found for ${capability.manifest.id}. Run: tabwright capability skill init ${capability.manifest.id}`)
+  }
+  const skillContent = fs.readFileSync(skillPath, 'utf-8')
+  assertSkillReadyToInstall({ capability, content: skillContent, filePath: skillPath })
+  const sourceFiles = getExistingAgentSkillFiles(dir)
+  const codexSkillDir = path.join(getCodexHome(options.codexHome), 'skills', capability.manifest.id)
+  const files = sourceFiles.map((file) => {
+    return writeSkillFile({
+      filePath: path.join(codexSkillDir, ...file.relativePath.split('/')),
+      relativePath: file.relativePath,
+      content: fs.readFileSync(file.path, 'utf-8'),
+      overwrite: options.overwrite,
+    })
+  })
+  return {
+    target,
+    capabilityId: capability.manifest.id,
+    dir: codexSkillDir,
+    files,
+    next: [`Restart or open a new agent thread so it can load the ${capability.manifest.id} skill.`],
+  }
+}
+
+export function showCapabilityAgentSkill(options: {
+  id: string
+  cwd?: string
+  target?: AgentSkillTarget
+}): CapabilityAgentSkillShowResult {
+  const target = options.target || 'codex'
+  const capability = requireCapability({ id: options.id, cwd: options.cwd })
+  const dir = getCapabilityAgentSkillDir({ capability, target })
+  const files = getExistingAgentSkillFiles(dir).map((file) => {
+    return {
+      relativePath: file.relativePath,
+      path: file.path,
+      content: fs.readFileSync(file.path, 'utf-8'),
+    }
+  })
+  if (!files.some((file) => {
+    return file.relativePath === 'SKILL.md'
+  })) {
+    throw new Error(`Agent skill draft not found for ${capability.manifest.id}. Run: tabwright capability skill init ${capability.manifest.id}`)
+  }
+  return {
+    target,
+    capabilityId: capability.manifest.id,
+    dir,
+    files,
+  }
+}
+
+export function getCapabilityAgentSkillStatus(options: {
+  capability: CapabilityRecord
+  target?: AgentSkillTarget
+  codexHome?: string
+}): CapabilityAgentSkillStatus {
+  const target = options.target || 'codex'
+  const draftDir = getCapabilityAgentSkillDir({ capability: options.capability, target })
+  const installedDir = path.join(getCodexHome(options.codexHome), 'skills', options.capability.manifest.id)
+  return {
+    target,
+    draftExists: fs.existsSync(path.join(draftDir, 'SKILL.md')),
+    draftPath: path.join(draftDir, 'SKILL.md'),
+    installedExists: fs.existsSync(path.join(installedDir, 'SKILL.md')),
+    installedPath: path.join(installedDir, 'SKILL.md'),
+    initCommand: `tabwright capability skill init ${options.capability.manifest.id}`,
+    showCommand: `tabwright capability skill show ${options.capability.manifest.id}`,
+    installCommand: `tabwright capability skill install ${options.capability.manifest.id}`,
+  }
+}
+
+function getCapabilityAgentSkillDir(options: { capability: CapabilityRecord; target: AgentSkillTarget }): string {
+  return path.join(options.capability.dir, 'agent-skills', options.target)
+}
+
+function getCodexHome(codexHome?: string): string {
+  return codexHome || process.env.CODEX_HOME || path.join(os.homedir(), '.codex')
+}
+
+function getExistingAgentSkillFiles(dir: string): Array<{ relativePath: string; path: string }> {
+  const skillPath = path.join(dir, 'SKILL.md')
+  const openAiPath = path.join(dir, 'agents', 'openai.yaml')
+  const files: Array<{ relativePath: string; path: string }> = []
+  if (fs.existsSync(skillPath)) {
+    files.push({ relativePath: 'SKILL.md', path: skillPath })
+  }
+  if (fs.existsSync(openAiPath)) {
+    files.push({ relativePath: 'agents/openai.yaml', path: openAiPath })
+  }
+  return files
+}
+
+function writeSkillFile(options: {
+  filePath: string
+  relativePath: string
+  content: string
+  overwrite?: boolean
+}): AgentSkillFileResult {
+  if (fs.existsSync(options.filePath)) {
+    const existing = fs.readFileSync(options.filePath, 'utf-8')
+    if (existing === options.content) {
+      return { relativePath: options.relativePath, path: options.filePath, status: 'unchanged' }
+    }
+    if (!options.overwrite) {
+      throw new Error(`Agent skill file already exists with different content: ${options.filePath}. Use --force to overwrite.`)
+    }
+  }
+  fs.mkdirSync(path.dirname(options.filePath), { recursive: true })
+  const status = fs.existsSync(options.filePath) ? 'updated' : 'created'
+  fs.writeFileSync(options.filePath, options.content)
+  return { relativePath: options.relativePath, path: options.filePath, status }
+}
+
+function assertSkillReadyToInstall(options: {
+  capability: CapabilityRecord
+  content: string
+  filePath: string
+}): void {
+  if (options.content.includes(SKILL_TEMPLATE_MARKER)) {
+    throw new Error(`Agent skill still contains the scaffold marker: ${options.filePath}. Edit the skill content before installing it.`)
+  }
+  if (!options.content.includes(`name: ${options.capability.manifest.id}`)) {
+    throw new Error(`Agent skill frontmatter must include name: ${options.capability.manifest.id}`)
+  }
+}
+
+function buildCodexSkillTemplate(capability: CapabilityRecord): string {
+  const operationIds = Object.keys(capability.manifest.operations)
+  const hasOperations = operationIds.length > 0
+  const requiresConfirmation = hasOperations
+    ? Object.values(capability.manifest.operations).some((operation) => {
+        return operation.requiresConfirmation
+      })
+    : capability.manifest.requiresConfirmation
+  const description = [
+    `TODO: Explain when agents should use the ${capability.manifest.id} Tabwright capability.`,
+    'Mention concrete user phrasing, exact-match signals, and when not to use it.',
+  ].join(' ')
+  const routeCommand = `tabwright capability route "<user-task-or-url>" --json`
+  const runCommand = [
+    'tabwright capability run',
+    capability.manifest.id,
+    capability.manifest.runtime === 'browser' ? '--browser user' : '',
+    "--input-json '<json-input>'",
+    '--json',
+    capability.manifest.status === 'trusted' ? '' : '--force',
+    requiresConfirmation
+      ? hasOperations
+        ? '--confirm <confirmation-token>'
+        : `--confirm ${capability.manifest.id}`
+      : '',
+  ]
+    .filter((part) => {
+      return part.length > 0
+    })
+    .join(' ')
+  return [
+    '---',
+    `name: ${capability.manifest.id}`,
+    `description: ${quoteYamlString(description)}`,
+    '---',
+    '',
+    SKILL_TEMPLATE_MARKER,
+    '',
+    '## When To Use',
+    '',
+    '- TODO: Describe the concrete user intent, URL pattern, page state, or data shape that should trigger this capability.',
+    '- TODO: State when this capability should not be used.',
+    '',
+    '## Workflow',
+    '',
+    '1. Use route when exact-match metadata may apply:',
+    '',
+    '```bash',
+    routeCommand,
+    '```',
+    '',
+    requiresConfirmation
+      ? hasOperations
+        ? `2. Select one operation (${operationIds.join(', ')}). Read operations may run directly; for a confirmation-required operation, stop for approval and use its exact confirmationToken:`
+        : '2. Stop and obtain explicit user approval for the concrete input and side effect. Only then run with structured input:'
+      : '2. Run the returned `shellCommand` exactly, or run the capability with structured input:',
+    '',
+    '```bash',
+    runCommand,
+    '```',
+    '',
+    '3. If the capability requires browser/session/auth state, describe the required refresh or browser command.',
+    '',
+    '## Output And Display',
+    '',
+    '- TODO: Define the default answer shape.',
+    '- TODO: Say when to show a short summary versus when to point to artifacts.',
+    '- TODO: Say whether large outputs should be saved, filtered, or exported only on request.',
+    '',
+  ].join('\n')
+}
+
+function buildOpenAiAgentTemplate(capability: CapabilityRecord): string {
+  return [
+    'interface:',
+    `  display_name: ${quoteYamlString(capability.manifest.title)}`,
+    `  short_description: ${quoteYamlString(capability.manifest.description || capability.manifest.title)}`,
+    `  default_prompt: ${quoteYamlString(`Use ${capability.manifest.id} for <task>`)}`,
+    '',
+  ].join('\n')
+}
+
+function quoteYamlString(value: string): string {
+  return JSON.stringify(value)
+}

package/src/capability-auth-state.ts

@@ -0,0 +1,197 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import {
+  readCapabilityRuns,
+  readCapabilitySecrets,
+  type CapabilityAuthType,
+  type CapabilityRecord,
+} from './capability-registry.js'
+
+const AUTH_STATE_FILENAME = 'auth-state.json'
+const EXPIRING_WINDOW_MS = 24 * 60 * 60 * 1000
+
+export type CapabilityAuthStatus = 'not-required' | 'missing' | 'authenticated' | 'expiring' | 'expired' | 'unknown'
+
+export interface StoredCapabilityAuthState {
+  schemaVersion: 1
+  refreshedAt: string
+  expiresAt?: string
+  cookieNames: string[]
+  browserKey?: string
+}
+
+export interface CapabilityAuthState {
+  type: CapabilityAuthType
+  status: CapabilityAuthStatus
+  canRefresh: boolean
+  browserUrls: string[]
+  requiredCookieNames: string[]
+  cookieNames: string[]
+  refreshedAt?: string
+  expiresAt?: string
+  browserKey?: string
+  reason?: string
+  refreshCommand?: string
+}
+
+export function writeStoredCapabilityAuthState(options: {
+  capability: CapabilityRecord
+  state: StoredCapabilityAuthState
+}): string {
+  const statePath = path.join(options.capability.dir, AUTH_STATE_FILENAME)
+  fs.mkdirSync(options.capability.dir, { recursive: true })
+  fs.writeFileSync(statePath, `${JSON.stringify(options.state, null, 2)}\n`, { mode: 0o600 })
+  if (process.platform !== 'win32') {
+    fs.chmodSync(statePath, 0o600)
+  }
+  return statePath
+}
+
+export function removeCapabilityAuthFiles(options: { capabilityDir: string }): void {
+  const filenames: string[] = ['secrets.json', AUTH_STATE_FILENAME]
+  filenames.map((filename) => {
+    fs.rmSync(path.join(options.capabilityDir, filename), { force: true })
+    return filename
+  })
+}
+
+export function getCapabilityAuthState(options: { capability: CapabilityRecord; now?: Date }): CapabilityAuthState {
+  const auth = options.capability.manifest.auth
+  const canRefresh = auth.type === 'cookie' && auth.refresh === 'from-browser' && auth.browserUrls.length > 0
+  const refreshCommand = canRefresh
+    ? `tabwright capability refresh-auth ${options.capability.manifest.id} --browser user --json`
+    : undefined
+  const base = {
+    type: auth.type,
+    canRefresh,
+    browserUrls: auth.browserUrls,
+    requiredCookieNames: auth.requiredCookieNames,
+    refreshCommand,
+  }
+  if (auth.type === 'none') {
+    return { ...base, status: 'not-required', cookieNames: [] }
+  }
+
+  const secretKey = auth.secretKey || 'cookieHeader'
+  const secrets = (() => {
+    try {
+      return readCapabilitySecrets({ capability: options.capability })
+    } catch {
+      return {}
+    }
+  })()
+  if (typeof secrets[secretKey] !== 'string' || secrets[secretKey].length === 0) {
+    return {
+      ...base,
+      status: 'missing',
+      cookieNames: [],
+      reason: 'No saved authentication is available on this device.',
+    }
+  }
+
+  const stored = readStoredCapabilityAuthState({ capability: options.capability })
+  if (!stored) {
+    return {
+      ...base,
+      status: 'unknown',
+      cookieNames: [],
+      reason: 'Saved authentication predates status tracking. Refresh it to inspect expiry.',
+    }
+  }
+
+  const runFailure = latestAuthFailure({ capability: options.capability, refreshedAt: stored.refreshedAt })
+  if (runFailure) {
+    return {
+      ...base,
+      ...stored,
+      status: 'expired',
+      reason: runFailure,
+    }
+  }
+
+  // Cookie timestamps cover client-side expiry; failure signals cover sessions revoked earlier by the server.
+  const now = options.now || new Date()
+  const expiresAt = stored.expiresAt ? Date.parse(stored.expiresAt) : Number.NaN
+  if (!Number.isNaN(expiresAt) && expiresAt <= now.getTime()) {
+    return {
+      ...base,
+      ...stored,
+      status: 'expired',
+      reason: 'The saved browser cookies have expired.',
+    }
+  }
+  if (!Number.isNaN(expiresAt) && expiresAt - now.getTime() <= EXPIRING_WINDOW_MS) {
+    return {
+      ...base,
+      ...stored,
+      status: 'expiring',
+      reason: 'The saved browser cookies expire within 24 hours.',
+    }
+  }
+  return { ...base, ...stored, status: 'authenticated' }
+}
+
+function readStoredCapabilityAuthState(options: { capability: CapabilityRecord }): StoredCapabilityAuthState | null {
+  const statePath = path.join(options.capability.dir, AUTH_STATE_FILENAME)
+  if (!fs.existsSync(statePath)) {
+    return null
+  }
+  const parsed: unknown = (() => {
+    try {
+      return JSON.parse(fs.readFileSync(statePath, 'utf-8'))
+    } catch {
+      return null
+    }
+  })()
+  if (!isRecord(parsed) || parsed.schemaVersion !== 1 || typeof parsed.refreshedAt !== 'string') {
+    return null
+  }
+  const cookieNames = Array.isArray(parsed.cookieNames)
+    ? parsed.cookieNames.filter((value): value is string => {
+        return typeof value === 'string'
+      })
+    : []
+  return {
+    schemaVersion: 1,
+    refreshedAt: parsed.refreshedAt,
+    expiresAt: typeof parsed.expiresAt === 'string' ? parsed.expiresAt : undefined,
+    cookieNames,
+    browserKey: typeof parsed.browserKey === 'string' ? parsed.browserKey : undefined,
+  }
+}
+
+function latestAuthFailure(options: { capability: CapabilityRecord; refreshedAt: string }): string | null {
+  const refreshedAt = Date.parse(options.refreshedAt)
+  const relevantRun = readCapabilityRuns({ capability: options.capability, limit: 50 })
+    .filter((run) => {
+      return Number.isNaN(refreshedAt) || Date.parse(run.createdAt) >= refreshedAt
+    })
+    .reverse()
+    .find((run) => {
+      if (run.status === 'success') {
+        return true
+      }
+      if (!run.error) {
+        return false
+      }
+      const normalizedError = run.error.toLowerCase()
+      return options.capability.manifest.auth.failureSignals.some((signal) => {
+        return normalizedError.includes(signal.toLowerCase())
+      })
+    })
+  if (!relevantRun || relevantRun.status === 'success' || !relevantRun.error) {
+    return null
+  }
+  const normalizedError = relevantRun.error.toLowerCase()
+  const matchedSignal = options.capability.manifest.auth.failureSignals.find((signal) => {
+    return normalizedError.includes(signal.toLowerCase())
+  })
+  if (!matchedSignal) {
+    return null
+  }
+  return `The latest run reported an authentication failure: ${matchedSignal}`
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}