buckyos 0.7.131 → 0.7.133

package/cli/modules/pikg_protocol.ts

@@ -77,6 +77,8 @@ export interface PikgInspectionResult {
   app: {
     did: string
     app_id: string
+    name?: string
+    app_type: string
     version: string
     owner: string
     app_doc_object_id: string
@@ -574,6 +576,8 @@ export async function inspectPikg(path: string): Promise<PikgInspectionResult> {
     app: {
       did: String(appDoc.did),
       app_id: appIdFromDid(String(appDoc.did)),
+      ...(typeof appDoc.name === 'string' ? { name: appDoc.name } : {}),
+      app_type: String(appDoc.app_type),
       version: String(appDoc.version),
       owner: String(appDoc.owner),
       app_doc_object_id: validated.appDocObjectId,
@@ -852,7 +856,7 @@ export function validateAppDocShape(appDoc: Record<string, unknown>): void {
     expectNonEmptyString(appDoc[field], `APPDOC.${field}`)
   }
   if (appDoc.doc_type !== 'app') throw invalid('appdoc', 'APPDOC.doc_type must be app')
-  if (!['service', 'dapp', 'web', 'agent'].includes(String(appDoc.app_type))) {
+  if (!['service', 'dapp', 'web', 'agent', 'agent_skills'].includes(String(appDoc.app_type))) {
     throw invalid('appdoc', 'APPDOC.app_type is invalid')
   }
   if (appDoc.name !== undefined) expectNonEmptyString(appDoc.name, 'APPDOC.name')
@@ -906,6 +910,12 @@ export function validateAppDocShape(appDoc: Record<string, unknown>): void {
   if (Object.keys(pkgList).length === 0) {
     throw invalid('appdoc', 'APPDOC.pkg_list must not be empty')
   }
+  if (appDoc.app_type === 'agent_skills') {
+    expectNonEmptyString(appDoc.name, 'APPDOC.name')
+    if (Object.keys(pkgList).join() !== 'agent_skills') {
+      throw invalid('appdoc', 'an agent_skills App must contain only the agent_skills sub package')
+    }
+  }
   deriveNamespaceForPackage(appDoc)
 }
 

package/cli/modules/share.ts

@@ -0,0 +1,356 @@
+import type { CommandDefinition, CommandModule, JsonSchema } from '../core/command.ts'
+import type { CommandContext } from '../core/context.ts'
+import { EXIT_INTERNAL, ToolError, UsageError } from '../core/errors.ts'
+import { expectObject, inputString, parseTimestamp, requiredInputString } from '../core/service.ts'
+
+// Share links of the Zone file service (nfs-server `share.*` over NFSP,
+// buckyos notepads/share-content-mgr-tech-design-todo.md §3.6).
+const OBJECT_OUTPUT: JsonSchema = { type: 'object', additionalProperties: true }
+const DAY_MS = 86_400_000
+const EXPIRES_HELP = '1d, 7d (default), 30d, none, or an RFC 3339 time'
+
+export function createShareModule(): CommandModule {
+  return {
+    name: 'share',
+    summary: 'Share files and folders as links, and manage what you have shared',
+    commands: [
+      createCommand(),
+      listCommand(),
+      getCommand(),
+      updateCommand(),
+      stopCommand(),
+      statsCommand(),
+    ],
+  }
+}
+
+interface NfspSession {
+  call(method: string, args: Record<string, unknown>, write?: boolean): Promise<Record<string, unknown>>
+}
+
+async function openNfsp(ctx: CommandContext): Promise<NfspSession> {
+  const session = ctx.session
+  if (!session) throw new ToolError('AUTH_REQUIRED', 'authenticated session is required', 3)
+  const token = (await session.ensureValid()).token
+  const base = gatewayOrigin(ctx.connection.endpoint)
+  let seq = 0
+  const post = async (method: string, body: Record<string, unknown>) => {
+    const response = await fetch(`${base}/nfs/v1/${method}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+      body: JSON.stringify(body),
+      signal: ctx.signal,
+    })
+    let parsed: { ok?: boolean; result?: unknown; error?: Record<string, unknown> }
+    try {
+      parsed = await response.json()
+    } catch {
+      throw new ToolError('INVALID_SERVICE_RESPONSE', `file service answered HTTP ${response.status}`, EXIT_INTERNAL)
+    }
+    if (parsed.ok !== true) {
+      const error = parsed.error ?? {}
+      const reason = typeof error.reason === 'string' ? error.reason.toUpperCase() : String(error.code ?? 'INTERNAL')
+      throw new ToolError(`SHARE_${reason}`, String(error.message ?? 'share request failed'))
+    }
+    return expectObject(parsed.result, `${method} result`)
+  }
+  const hello = await post('hello', { args: { versions: ['nfsp/0'] } })
+  const sessionId = String(hello.session ?? '')
+  if (!Array.isArray(hello.features) || !hello.features.includes('share')) {
+    throw new ToolError('SHARE_UNSUPPORTED', 'the file service of this Zone does not support sharing')
+  }
+  return {
+    call: (method, args, write = false) =>
+      post(method, { session: sessionId, args: { ...args, source_hint: 'cli' }, ...(write ? { seq: ++seq } : {}) }),
+  }
+}
+
+function gatewayOrigin(endpoint: string): string {
+  const url = new URL(endpoint)
+  const marker = url.pathname.indexOf('/kapi')
+  url.pathname = marker >= 0 ? url.pathname.slice(0, marker) || '/' : '/'
+  url.search = ''
+  url.hash = ''
+  return url.toString().replace(/\/$/, '')
+}
+
+/** `--expires` → unix seconds, `null` for no expiry, `undefined` for the server default (7 days). */
+export function parseExpires(value: unknown): number | null | undefined {
+  if (value === undefined) return undefined
+  const text = String(value).trim().toLowerCase()
+  if (text === 'none' || text === 'never') return null
+  const days = text.match(/^(\d+)d$/)
+  if (days) return Math.floor((Date.now() + Number(days[1]) * DAY_MS) / 1000)
+  const at = parseTimestamp(value, 'expires')
+  if (at === undefined) return undefined
+  if (at <= Date.now()) throw new UsageError('INVALID_ARGUMENT', 'expires must be in the future')
+  return Math.floor(at / 1000)
+}
+
+function sourceLocator(path: string): Record<string, unknown> {
+  if (path.startsWith('cyfs://')) return { uri: path }
+  return { path: path.startsWith('/') ? path : `/${path}` }
+}
+
+function summary(share: Record<string, unknown>): Record<string, unknown> {
+  const keep = ['share_id', 'kind', 'title', 'status', 'access', 'expires_at', 'url', 'target_app', 'delivery_state', 'source_path', 'revision', 'created_at', 'stats']
+  return Object.fromEntries(keep.filter((key) => share[key] !== undefined).map((key) => [key, share[key]]))
+}
+
+function createCommand(): CommandDefinition {
+  return {
+    verb: 'create',
+    summary: 'Share a file or folder as a link (a snapshot of its current content)',
+    positionals: [{ name: 'path', description: 'File or folder, e.g. /home/alice/report.pdf or cyfs:///home/alice/report.pdf', required: true }],
+    options: [
+      { name: 'expires', description: `Link expiry: ${EXPIRES_HELP}`, type: 'string' },
+      { name: 'password', description: 'Require this password to open the link', type: 'string' },
+      { name: 'title', description: 'Title shown to visitors', type: 'string' },
+      { name: 'no-download', property: 'no_download', description: 'Preview only, no download button', type: 'boolean' },
+      { name: 'wait', description: 'Wait for a large snapshot to finish', type: 'boolean' },
+    ],
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', minLength: 1 },
+        expires: { type: 'string', minLength: 1 },
+        password: { type: 'string', minLength: 1 },
+        title: { type: 'string', minLength: 1 },
+        no_download: { type: 'boolean' },
+        wait: { type: 'boolean' },
+      },
+      required: ['path'],
+      additionalProperties: false,
+    },
+    outputSchema: OBJECT_OUTPUT,
+    resultSchemaVersion: 1,
+    access: { mode: 'fixed', level: 'write' },
+    asyncMode: 'either',
+    requiresSession: true,
+    examples: [
+      'buckyos share create /home/alice/report.pdf',
+      'buckyos share create /home/alice/photos --expires 30d --password s3cret',
+    ],
+    handler: async (ctx, input) => {
+      const nfsp = await openNfsp(ctx)
+      const expires = parseExpires(input.expires)
+      const password = inputString(input, 'password')
+      const policy: Record<string, unknown> = {
+        access: password ? 'password' : 'holder',
+        allow_download: input.no_download !== true,
+        ...(password ? { password } : {}),
+        ...(expires !== undefined ? { expires_at: expires } : {}),
+      }
+      let op = await nfsp.call('share.create', {
+        source: sourceLocator(requiredInputString(input, 'path')),
+        policy,
+        title: inputString(input, 'title'),
+        idempotency_key: ctx.idempotencyKey ?? crypto.randomUUID(),
+      }, true)
+      while (input.wait === true && (op.state === 'running' || op.state === 'preparing')) {
+        await new Promise((resolve) => setTimeout(resolve, 1000))
+        ctx.signal.throwIfAborted()
+        op = await nfsp.call('share.operation', { operation_id: op.operation_id })
+      }
+      if (op.state === 'failed' || op.state === 'canceled') {
+        const error = (op.error ?? {}) as Record<string, unknown>
+        throw new ToolError(`SHARE_${String(error.reason ?? op.state).toUpperCase()}`, String(error.message ?? `share ${op.state}`))
+      }
+      return {
+        operation_id: op.operation_id,
+        state: op.state,
+        share_id: op.share_id ?? null,
+        url: op.url ?? null,
+        source_changed: op.source_changed ?? false,
+        ...(op.share ? { share: summary(op.share as Record<string, unknown>) } : {}),
+      }
+    },
+  }
+}
+
+function listCommand(): CommandDefinition {
+  return {
+    verb: 'list',
+    summary: 'List your shares',
+    options: [
+      { name: 'kind', description: 'link or app_delivery', type: 'string', enum: ['link', 'app_delivery'] },
+      { name: 'status', description: 'active, stopped, expired, ...', type: 'string' },
+      { name: 'q', description: 'Search title and path', type: 'string' },
+      { name: 'include-hidden', property: 'include_hidden', description: 'Include hidden shares', type: 'boolean' },
+      { name: 'cursor', description: 'Page cursor', type: 'string' },
+      { name: 'limit', description: 'Page size, at most 200', type: 'integer' },
+    ],
+    inputSchema: {
+      type: 'object',
+      properties: {
+        kind: { type: 'string', enum: ['link', 'app_delivery'] },
+        status: { type: 'string', minLength: 1 },
+        q: { type: 'string', minLength: 1 },
+        include_hidden: { type: 'boolean' },
+        cursor: { type: 'string', minLength: 1 },
+        limit: { type: 'integer', minimum: 1 },
+      },
+      additionalProperties: false,
+    },
+    outputSchema: OBJECT_OUTPUT,
+    resultSchemaVersion: 1,
+    access: { mode: 'fixed', level: 'read' },
+    asyncMode: 'sync',
+    requiresSession: true,
+    examples: ['buckyos share list --kind link --status active'],
+    handler: async (ctx, input) => {
+      const nfsp = await openNfsp(ctx)
+      const page = await nfsp.call('share.list', {
+        kind: input.kind,
+        status: input.status,
+        q: input.q,
+        include_hidden: input.include_hidden === true,
+        cursor: input.cursor,
+        limit: input.limit,
+      })
+      const items = Array.isArray(page.items) ? page.items as Record<string, unknown>[] : []
+      return { items: items.map(summary), next_cursor: page.next_cursor ?? null }
+    },
+  }
+}
+
+function getCommand(): CommandDefinition {
+  return {
+    verb: 'get',
+    summary: 'Show one share: link, policy, snapshot, delivery, statistics and history',
+    positionals: [{ name: 'share_id', description: 'Share ID (sh_…)', required: true }],
+    inputSchema: {
+      type: 'object',
+      properties: { share_id: { type: 'string', minLength: 1 } },
+      required: ['share_id'],
+      additionalProperties: false,
+    },
+    outputSchema: OBJECT_OUTPUT,
+    resultSchemaVersion: 1,
+    access: { mode: 'fixed', level: 'read' },
+    asyncMode: 'sync',
+    requiresSession: true,
+    examples: ['buckyos share get sh_0123456789abcdef'],
+    handler: async (ctx, input) => {
+      const nfsp = await openNfsp(ctx)
+      return await nfsp.call('share.get', { share_id: requiredInputString(input, 'share_id') })
+    },
+  }
+}
+
+function updateCommand(): CommandDefinition {
+  return {
+    verb: 'update',
+    summary: 'Change a link\'s expiry, password, title or download setting',
+    positionals: [{ name: 'share_id', description: 'Share ID (sh_…)', required: true }],
+    options: [
+      { name: 'expires', description: `New expiry: ${EXPIRES_HELP}`, type: 'string' },
+      { name: 'password', description: 'Set or change the password', type: 'string' },
+      { name: 'no-password', property: 'no_password', description: 'Remove the password', type: 'boolean' },
+      { name: 'title', description: 'New title', type: 'string' },
+      { name: 'download', description: 'Allow (true) or forbid (false) downloading', type: 'boolean' },
+    ],
+    inputSchema: {
+      type: 'object',
+      properties: {
+        share_id: { type: 'string', minLength: 1 },
+        expires: { type: 'string', minLength: 1 },
+        password: { type: 'string', minLength: 1 },
+        no_password: { type: 'boolean' },
+        title: { type: 'string', minLength: 1 },
+        download: { type: 'boolean' },
+      },
+      required: ['share_id'],
+      additionalProperties: false,
+    },
+    outputSchema: OBJECT_OUTPUT,
+    resultSchemaVersion: 1,
+    access: { mode: 'fixed', level: 'write' },
+    asyncMode: 'sync',
+    requiresSession: true,
+    examples: ['buckyos share update sh_0123456789abcdef --expires none', 'buckyos share update sh_0123456789abcdef --password n3w'],
+    handler: async (ctx, input) => {
+      if (input.password !== undefined && input.no_password === true) {
+        throw new UsageError('INVALID_ARGUMENT', 'use either --password or --no-password')
+      }
+      const changes: Record<string, unknown> = {}
+      const expires = parseExpires(input.expires)
+      if (expires !== undefined) changes.expires_at = expires
+      if (input.password !== undefined) changes.password = String(input.password)
+      if (input.no_password === true) changes.password = null
+      if (input.title !== undefined) changes.title = String(input.title)
+      if (input.download !== undefined) changes.allow_download = input.download === true
+      if (!Object.keys(changes).length) throw new UsageError('INVALID_ARGUMENT', 'nothing to change')
+      const nfsp = await openNfsp(ctx)
+      const shareId = requiredInputString(input, 'share_id')
+      const current = await nfsp.call('share.get', { share_id: shareId })
+      const result = await nfsp.call('share.update', { share_id: shareId, revision: current.revision, changes }, true)
+      return { revision: result.revision, share: summary(expectObject(result.share, 'share.update share')) }
+    },
+  }
+}
+
+function stopCommand(): CommandDefinition {
+  return {
+    verb: 'stop',
+    summary: 'Stop a share: the link stops working and the kept snapshot is released',
+    positionals: [{ name: 'share_id', description: 'Share ID (sh_…)', required: true }],
+    options: [{ name: 'reason', description: 'Recorded in the share history', type: 'string' }],
+    inputSchema: {
+      type: 'object',
+      properties: { share_id: { type: 'string', minLength: 1 }, reason: { type: 'string', minLength: 1 } },
+      required: ['share_id'],
+      additionalProperties: false,
+    },
+    outputSchema: OBJECT_OUTPUT,
+    resultSchemaVersion: 1,
+    access: { mode: 'fixed', level: 'destructive' },
+    asyncMode: 'sync',
+    requiresSession: true,
+    examples: ['buckyos share stop sh_0123456789abcdef --reason "sent by mistake"'],
+    handler: async (ctx, input) => {
+      const nfsp = await openNfsp(ctx)
+      const shareId = requiredInputString(input, 'share_id')
+      const current = await nfsp.call('share.get', { share_id: shareId })
+      return await nfsp.call('share.stop', { share_id: shareId, revision: current.revision, reason: inputString(input, 'reason') }, true)
+    },
+  }
+}
+
+function statsCommand(): CommandDefinition {
+  return {
+    verb: 'stats',
+    summary: 'Views, downloads, traffic and visitors of one share or all of yours',
+    options: [
+      { name: 'share-id', property: 'share_id', description: 'One share instead of all', type: 'string' },
+      { name: 'days', description: 'How many days back (default 30)', type: 'integer' },
+      { name: 'granularity', description: 'day or hour', type: 'string', enum: ['day', 'hour'] },
+    ],
+    inputSchema: {
+      type: 'object',
+      properties: {
+        share_id: { type: 'string', minLength: 1 },
+        days: { type: 'integer', minimum: 1 },
+        granularity: { type: 'string', enum: ['day', 'hour'] },
+      },
+      additionalProperties: false,
+    },
+    outputSchema: OBJECT_OUTPUT,
+    resultSchemaVersion: 1,
+    access: { mode: 'fixed', level: 'read' },
+    asyncMode: 'sync',
+    requiresSession: true,
+    examples: ['buckyos share stats --days 7', 'buckyos share stats --share-id sh_0123456789abcdef --granularity hour --days 2'],
+    handler: async (ctx, input) => {
+      const nfsp = await openNfsp(ctx)
+      const to = Math.floor(Date.now() / 1000) + 1
+      const days = typeof input.days === 'number' ? input.days : 30
+      return await nfsp.call('share.stats', {
+        share_id: inputString(input, 'share_id'),
+        from: to - days * 86_400,
+        to,
+        granularity: input.granularity ?? 'day',
+      })
+    },
+  }
+}

package/cli/modules/skill.ts

@@ -0,0 +1,256 @@
+import type { CommandModule, JsonSchema, OptionDefinition } from '../core/command.ts'
+import type { CommandContext } from '../core/context.ts'
+import { EXIT_INTERNAL, EXIT_PERMISSION, ToolError, UsageError } from '../core/errors.ts'
+import { callService, requiredInputString } from '../core/service.ts'
+import { getHost } from '../runtime/host.ts'
+import { openZip, readTarGz, readZipEntry, sha256Bytes } from './pikg_archive.ts'
+import { inspectPikg } from './pikg_protocol.ts'
+
+const OBJECT_OUTPUT: JsonSchema = { type: 'object', additionalProperties: true }
+const SKILL_KINDS = ['cmd', 'goal']
+const SKILLS_SUB_PKG = 'agent_skills'
+const SKILL_DIRS = ['cmd_skills', 'goal_skills', 'tools']
+const MAX_SKILL_PAYLOAD_BYTES = 64 * 1024 * 1024
+const AGENT_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+
+const AGENT_OPTION: OptionDefinition = {
+  name: 'agent',
+  property: 'agent_id',
+  description: 'Agent ID; the Agent serves kRPC at /kapi/<agent_id>',
+  type: 'string',
+  required: true,
+}
+
+const KIND_OPTION: OptionDefinition = {
+  name: 'kind',
+  description: 'Skill kind',
+  type: 'string',
+  enum: SKILL_KINDS,
+}
+
+export function createSkillModule(): CommandModule {
+  return {
+    name: 'skill',
+    summary: 'List, install, and remove the cmd/goal skills of an Agent',
+    commands: [
+      {
+        verb: 'list',
+        summary: 'List the skills of an Agent',
+        options: [AGENT_OPTION, KIND_OPTION],
+        inputSchema: {
+          type: 'object',
+          properties: {
+            agent_id: { type: 'string', minLength: 1 },
+            kind: { type: 'string', enum: SKILL_KINDS },
+          },
+          required: ['agent_id'],
+          additionalProperties: false,
+        },
+        outputSchema: OBJECT_OUTPUT,
+        resultSchemaVersion: 1,
+        access: { mode: 'fixed', level: 'read' },
+        asyncMode: 'sync',
+        requiresSession: true,
+        examples: [
+          'buckyos skill list --agent jarvis.example.zone',
+          'buckyos skill list --agent jarvis.example.zone --kind cmd',
+        ],
+        handler: async (ctx, input) => {
+          const agentId = agentIdFrom(input)
+          const kind = typeof input.kind === 'string' ? input.kind : undefined
+          const skills = await listSkills(ctx, agentId, kind)
+          return { agent_id: agentId, ...(kind ? { kind } : {}), total: skills.length, skills }
+        },
+      },
+      {
+        verb: 'install',
+        summary: 'Install the skills of a skill PIKG into an Agent',
+        description:
+          'Verifies the PIKG offline, requires app_type agent_skills, and sends the files of its agent_skills sub package (cmd_skills/, goal_skills/, tools/) to the Agent. Sessions created before keep their frozen manuals.',
+        positionals: [{ name: 'pikg_path', description: 'Local skill .pikg file' }],
+        options: [
+          AGENT_OPTION,
+          {
+            name: 'replace',
+            description: 'Replace skills of the same names from another package',
+            type: 'boolean',
+          },
+        ],
+        inputSchema: {
+          type: 'object',
+          properties: {
+            pikg_path: { type: 'string', minLength: 1 },
+            agent_id: { type: 'string', minLength: 1 },
+            replace: { type: 'boolean' },
+          },
+          required: ['pikg_path', 'agent_id'],
+          additionalProperties: false,
+        },
+        outputSchema: OBJECT_OUTPUT,
+        resultSchemaVersion: 1,
+        access: { mode: 'fixed', level: 'write' },
+        asyncMode: 'sync',
+        requiresSession: true,
+        examples: [
+          'buckyos skill install ./dapp_dist/hello-skills-0.1.0.pikg --agent jarvis.example.zone',
+          'buckyos skill install ./hello-skills-0.2.0.pikg --agent jarvis.example.zone --replace',
+        ],
+        handler: async (ctx, input) => await installSkills(ctx, input),
+      },
+      {
+        verb: 'remove',
+        summary: 'Remove an installed skill from an Agent',
+        description:
+          'Only installed skills can be removed. Without --kind the kind is looked up by name.',
+        positionals: [{ name: 'name', description: 'Skill name' }],
+        options: [AGENT_OPTION, KIND_OPTION],
+        inputSchema: {
+          type: 'object',
+          properties: {
+            name: { type: 'string', minLength: 1 },
+            agent_id: { type: 'string', minLength: 1 },
+            kind: { type: 'string', enum: SKILL_KINDS },
+          },
+          required: ['name', 'agent_id'],
+          additionalProperties: false,
+        },
+        outputSchema: OBJECT_OUTPUT,
+        resultSchemaVersion: 1,
+        access: { mode: 'fixed', level: 'destructive' },
+        asyncMode: 'sync',
+        requiresSession: true,
+        examples: ['buckyos --yes skill remove hello --agent jarvis.example.zone --kind cmd'],
+        handler: async (ctx, input) => await removeSkill(ctx, input),
+      },
+    ],
+  }
+}
+
+async function installSkills(
+  ctx: CommandContext,
+  input: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const agentId = agentIdFrom(input)
+  const raw = requiredInputString(input, 'pikg_path')
+  const path = getHost().path.isAbsolute(raw)
+    ? getHost().path.resolve(raw)
+    : getHost().path.resolve(ctx.cwd, raw)
+  const inspection = await inspectPikg(path)
+  if (inspection.app.app_type !== SKILLS_SUB_PKG) {
+    throw new UsageError(
+      'NOT_A_SKILL_PACKAGE',
+      `PIKG app_type is ${inspection.app.app_type}; a skill package has app_type ${SKILLS_SUB_PKG} (buckyos pikg init --kind agent-skills)`,
+    )
+  }
+  const payload = inspection.subpackages.find((item) => item.key === SKILLS_SUB_PKG)
+    ?.payload as { path: string; digest: string }
+  const archive = await openZip(path)
+  const bytes = await readZipEntry(
+    archive,
+    archive.byName.get(payload.path)!,
+    MAX_SKILL_PAYLOAD_BYTES,
+  )
+  if (`sha256:${sha256Bytes(bytes)}` !== payload.digest) {
+    throw new ToolError('INVALID_PACKAGE', 'PIKG changed after it was verified')
+  }
+  const files: Record<string, { content: string; executable: boolean }> = {}
+  const ignored: string[] = []
+  for (const entry of await readTarGz(bytes, MAX_SKILL_PAYLOAD_BYTES)) {
+    if (!SKILL_DIRS.includes(entry.path.split('/')[0])) {
+      ignored.push(entry.path)
+      continue
+    }
+    files[entry.path] = { content: base64(entry.bytes), executable: entry.executable }
+  }
+  const result = await callService<unknown>(ctx, agentId, 'skills.install', {
+    package: {
+      package: inspection.app.name,
+      version: inspection.app.version,
+      pikg_digest: inspection.pikg_digest,
+      files,
+    },
+    replace: input.replace === true,
+  })
+  return {
+    agent_id: agentId,
+    pikg_path: inspection.pikg_path,
+    pikg_digest: inspection.pikg_digest,
+    ...expectObject(result, 'skills.install'),
+    ...(ignored.length ? { ignored_files: ignored } : {}),
+  }
+}
+
+async function removeSkill(
+  ctx: CommandContext,
+  input: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  const agentId = agentIdFrom(input)
+  const name = requiredInputString(input, 'name')
+  let kind = typeof input.kind === 'string' ? input.kind : undefined
+  if (!kind) {
+    const kinds = (await listSkills(ctx, agentId)).filter((skill) => skill.name === name)
+      .map((skill) => String(skill.kind))
+    if (kinds.length === 0) {
+      throw new ToolError('RESOURCE_NOT_FOUND', `Agent ${agentId} has no skill named ${name}`)
+    }
+    if (kinds.length > 1) {
+      throw new UsageError('AMBIGUOUS_SKILL', `${name} is both a cmd and a goal skill; use --kind`)
+    }
+    kind = kinds[0]
+  }
+  if (!ctx.confirmed) {
+    if (ctx.config.nonInteractive || !ctx.io.inputIsTerminal) {
+      throw new ToolError(
+        'CONFIRMATION_REQUIRED',
+        'skill remove requires --yes in non-interactive execution',
+        EXIT_PERMISSION,
+      )
+    }
+    const answer = (await ctx.io.prompt(`Remove ${kind} skill ${name} from ${agentId}? [y/N] `))
+      ?.trim().toLowerCase()
+    if (answer !== 'y' && answer !== 'yes') {
+      throw new ToolError('CONFIRMATION_DECLINED', 'skill remove was declined', EXIT_PERMISSION)
+    }
+  }
+  const removed = await callService<unknown>(ctx, agentId, 'skills.remove', { kind, name })
+  return { agent_id: agentId, removed: expectObject(removed, 'skills.remove') }
+}
+
+async function listSkills(
+  ctx: CommandContext,
+  agentId: string,
+  kind?: string,
+): Promise<Record<string, unknown>[]> {
+  const skills = await callService<unknown>(ctx, agentId, 'skills.list', kind ? { kind } : {})
+  if (!Array.isArray(skills)) invalidResponse('skills.list')
+  return (skills as unknown[]).map((skill) => expectObject(skill, 'skills.list'))
+}
+
+function agentIdFrom(input: Record<string, unknown>): string {
+  const agentId = requiredInputString(input, 'agent_id')
+  if (!AGENT_ID.test(agentId)) {
+    throw new UsageError('INVALID_AGENT_ID', `invalid Agent ID: ${agentId}`)
+  }
+  return agentId
+}
+
+function expectObject(value: unknown, method: string): Record<string, unknown> {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) invalidResponse(method)
+  return value as Record<string, unknown>
+}
+
+function invalidResponse(method: string): never {
+  throw new ToolError(
+    'INVALID_SERVICE_RESPONSE',
+    `Agent returned an invalid response for ${method}`,
+    EXIT_INTERNAL,
+  )
+}
+
+function base64(bytes: Uint8Array): string {
+  let binary = ''
+  for (let index = 0; index < bytes.length; index += 0x8000) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + 0x8000))
+  }
+  return btoa(binary)
+}