buckyos 0.7.131 → 0.7.133

package/cli/modules/agent.ts

@@ -0,0 +1,165 @@
+import type { CommandModule, JsonSchema, PositionalDefinition } from '../core/command.ts'
+import type { CommandContext } from '../core/context.ts'
+import { EXIT_INTERNAL, ToolError, UsageError } from '../core/errors.ts'
+import { callService, expectObject, requiredInputString } from '../core/service.ts'
+
+const CONTROL_PANEL = 'control-panel'
+const OBJECT_OUTPUT: JsonSchema = { type: 'object', additionalProperties: true }
+const AGENT_POSITIONAL: PositionalDefinition = {
+  name: 'agent_id',
+  description: 'Agent ID as `agent list` prints it (raw host name, e.g. jarvis.example.zone)',
+}
+const AGENT_INPUT: JsonSchema = {
+  type: 'object',
+  properties: { agent_id: { type: 'string', minLength: 1 } },
+  required: ['agent_id'],
+  additionalProperties: false,
+}
+const PROFILE_FIELDS = ['display_name', 'bio']
+
+// Control Panel answers for Agents the caller owns; admins (and the device identity) see all.
+export function createAgentModule(): CommandModule {
+  return {
+    name: 'agent',
+    summary: 'List Agents and read or change their profiles',
+    commands: [
+      {
+        verb: 'list',
+        summary: 'List the Agents visible to the caller',
+        description: 'Owners see their own Agents; admins see every Agent in the Zone.',
+        inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+        outputSchema: {
+          type: 'object',
+          properties: { agents: { type: 'array', items: OBJECT_OUTPUT } },
+          required: ['agents'],
+          additionalProperties: false,
+        },
+        resultSchemaVersion: 1,
+        access: { mode: 'fixed', level: 'read' },
+        asyncMode: 'sync',
+        requiresSession: true,
+        examples: ['buckyos agent list'],
+        handler: async (ctx) => {
+          const response = await callAgent(ctx, 'agent.list', {})
+          if (!Array.isArray(response.agents)) {
+            throw new ToolError(
+              'INVALID_SERVICE_RESPONSE',
+              'agent.list agents must be an array',
+              EXIT_INTERNAL,
+            )
+          }
+          return { agents: response.agents }
+        },
+      },
+      {
+        verb: 'get',
+        summary: 'Get one Agent: profile, settings, install state, template, and runtime',
+        positionals: [AGENT_POSITIONAL],
+        inputSchema: AGENT_INPUT,
+        outputSchema: OBJECT_OUTPUT,
+        resultSchemaVersion: 1,
+        access: { mode: 'fixed', level: 'read' },
+        asyncMode: 'sync',
+        requiresSession: true,
+        examples: ['buckyos agent get jarvis.example.zone'],
+        handler: async (ctx, input) =>
+          await callAgent(ctx, 'agent.get', { agent_id: requiredInputString(input, 'agent_id') }),
+      },
+      {
+        verb: 'profile-get',
+        summary: 'Get the public profile (display name, bio, avatar) of an Agent',
+        positionals: [AGENT_POSITIONAL],
+        inputSchema: AGENT_INPUT,
+        outputSchema: OBJECT_OUTPUT,
+        resultSchemaVersion: 1,
+        access: { mode: 'fixed', level: 'read' },
+        asyncMode: 'sync',
+        requiresSession: true,
+        examples: ['buckyos agent profile-get jarvis.example.zone'],
+        handler: async (ctx, input) => {
+          const agentId = requiredInputString(input, 'agent_id')
+          return {
+            agent_id: agentId,
+            ...await callAgent(ctx, 'agent.profile.get', { agent_id: agentId }),
+          }
+        },
+      },
+      {
+        verb: 'profile-set',
+        summary: 'Change the display name or bio of an Agent',
+        description:
+          'Only the given fields change; an empty value clears the field. Returns the profile before and after the change, and Message Center reloads the new name.',
+        positionals: [AGENT_POSITIONAL],
+        options: [
+          {
+            name: 'display-name',
+            description: 'New display name; empty clears it',
+            type: 'string',
+          },
+          { name: 'bio', description: 'New bio; empty clears it', type: 'string' },
+        ],
+        inputSchema: {
+          type: 'object',
+          properties: {
+            agent_id: { type: 'string', minLength: 1 },
+            display_name: { type: 'string' },
+            bio: { type: 'string' },
+          },
+          required: ['agent_id'],
+          additionalProperties: false,
+        },
+        outputSchema: {
+          type: 'object',
+          properties: {
+            agent_id: { type: 'string' },
+            before: OBJECT_OUTPUT,
+            profile: OBJECT_OUTPUT,
+          },
+          required: ['agent_id', 'before', 'profile'],
+          additionalProperties: false,
+        },
+        resultSchemaVersion: 1,
+        access: { mode: 'fixed', level: 'write' },
+        asyncMode: 'sync',
+        requiresSession: true,
+        examples: [
+          "buckyos agent profile-set jarvis.example.zone --display-name 'Jarvis'",
+          "buckyos agent profile-set jarvis.example.zone --bio ''",
+        ],
+        handler: async (ctx, input) => {
+          const agentId = requiredInputString(input, 'agent_id')
+          const changes = Object.fromEntries(
+            PROFILE_FIELDS.filter((field) => typeof input[field] === 'string')
+              .map((field) => [field, input[field]]),
+          )
+          if (Object.keys(changes).length === 0) {
+            throw new UsageError('INVALID_ARGUMENT', 'give --display-name or --bio')
+          }
+          const before = await callAgent(ctx, 'agent.profile.get', { agent_id: agentId })
+          const after = await callAgent(ctx, 'agent.profile.set', { agent_id: agentId, ...changes })
+          return {
+            agent_id: agentId,
+            before: expectObject(before.profile, 'agent.profile.get profile'),
+            profile: expectObject(after.profile, 'agent.profile.set profile'),
+          }
+        },
+      },
+    ],
+  }
+}
+
+async function callAgent(
+  ctx: CommandContext,
+  method: string,
+  params: Record<string, unknown>,
+): Promise<Record<string, unknown>> {
+  try {
+    return expectObject(await callService(ctx, CONTROL_PANEL, method, params), method)
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    if (message.includes('agent_not_found')) {
+      throw new ToolError('RESOURCE_NOT_FOUND', `Agent not found or not yours: ${params.agent_id}`)
+    }
+    throw error
+  }
+}

package/cli/modules/ai.ts

@@ -0,0 +1,160 @@
+import type { CommandDefinition, CommandModule, JsonSchema } from '../core/command.ts'
+import { UsageError } from '../core/errors.ts'
+import {
+  callService,
+  expectObject,
+  inputString,
+  parseTimestamp,
+  splitServices,
+} from '../core/service.ts'
+
+const AICC = 'aicc'
+const OBJECT_OUTPUT: JsonSchema = { type: 'object', additionalProperties: true }
+const EMPTY_INPUT: JsonSchema = { type: 'object', properties: {}, additionalProperties: false }
+const RANGES = ['last1d', 'last7d', 'last30d']
+const GROUPS = [
+  'provider_instance_name',
+  'provider_model',
+  'request_model',
+  'method',
+  'capability',
+  'caller_app_id',
+  'user_id',
+  'tenant_id',
+]
+
+// Read views of the AICC service (/kapi/aicc); provider and routing changes stay in Control Panel.
+export function createAiModule(): CommandModule {
+  return {
+    name: 'ai',
+    summary: 'Read AI provider, routing, and usage state of the AICC service',
+    commands: [
+      readCommand({
+        verb: 'providers',
+        summary: 'List configured AI provider instances with auth, health, and model inventory',
+        method: 'provider.list',
+        description:
+          'Credentials are reported only as configured/kind; secrets are never returned.',
+      }),
+      readCommand({
+        verb: 'routing',
+        summary: 'Get the AICC routing overlay and its settings revision',
+        method: 'routing.get',
+        description: 'An empty routing object means the default routing of the model catalog.',
+      }),
+      usageCommand(),
+    ],
+  }
+}
+
+function readCommand(options: {
+  verb: string
+  summary: string
+  method: string
+  description: string
+}): CommandDefinition {
+  return {
+    verb: options.verb,
+    summary: options.summary,
+    description: options.description,
+    inputSchema: EMPTY_INPUT,
+    outputSchema: OBJECT_OUTPUT,
+    resultSchemaVersion: 1,
+    access: { mode: 'fixed', level: 'read' },
+    asyncMode: 'sync',
+    requiresSession: true,
+    examples: [`buckyos ai ${options.verb}`],
+    handler: async (ctx) =>
+      expectObject(await callService(ctx, AICC, options.method, {}), options.method),
+  }
+}
+
+function usageCommand(): CommandDefinition {
+  return {
+    verb: 'usage',
+    summary: "Aggregate the caller's AI usage: requests, tokens, and cost",
+    description:
+      "Scoped to the caller's own user (a device identity sees only its own calls, not the Zone total). Without --since the range defaults to last7d; --until defaults to now.",
+    options: [
+      {
+        name: 'range',
+        description: 'last1d, last7d (default), or last30d',
+        type: 'string',
+        enum: RANGES,
+      },
+      { name: 'since', description: 'RFC 3339 or Unix ms lower bound', type: 'string' },
+      { name: 'until', description: 'RFC 3339 or Unix ms upper bound', type: 'string' },
+      {
+        name: 'group-by',
+        description: `Comma-separated: ${GROUPS.join(', ')}`,
+        type: 'string',
+      },
+      {
+        name: 'bucket',
+        description: 'Time buckets: hour or day',
+        type: 'string',
+        enum: ['hour', 'day'],
+      },
+      { name: 'events', description: 'Also return the individual usage events', type: 'boolean' },
+      { name: 'limit', description: 'Event page size', type: 'integer' },
+      { name: 'cursor', description: 'Opaque event page cursor', type: 'string' },
+    ],
+    inputSchema: {
+      type: 'object',
+      properties: {
+        range: { type: 'string', enum: RANGES },
+        since: { type: 'string', minLength: 1 },
+        until: { type: 'string', minLength: 1 },
+        group_by: { type: 'string', minLength: 1 },
+        bucket: { type: 'string', enum: ['hour', 'day'] },
+        events: { type: 'boolean' },
+        limit: { type: 'integer', minimum: 1 },
+        cursor: { type: 'string', minLength: 1 },
+      },
+      additionalProperties: false,
+    },
+    outputSchema: OBJECT_OUTPUT,
+    resultSchemaVersion: 1,
+    access: { mode: 'fixed', level: 'read' },
+    asyncMode: 'sync',
+    requiresSession: true,
+    examples: [
+      'buckyos ai usage --range last1d --group-by provider_instance_name,provider_model',
+      'buckyos ai usage --since 2026-10-01T00:00:00Z --bucket day',
+    ],
+    handler: async (ctx, input) => {
+      const groupBy = splitServices(input.group_by)
+      const unknown = groupBy.filter((group) => !GROUPS.includes(group))
+      if (unknown.length > 0) {
+        throw new UsageError(
+          'INVALID_ARGUMENT',
+          `unknown group-by ${unknown.join(', ')}; use ${GROUPS.join(', ')}`,
+        )
+      }
+      return expectObject(
+        await callService(ctx, AICC, 'usage.query', {
+          time_range: timeRange(input),
+          ...(groupBy.length > 0 ? { group_by: groupBy } : {}),
+          ...(input.bucket ? { time_bucket: input.bucket } : {}),
+          output_mode: input.events === true ? 'summary_and_events' : 'summary',
+          ...(input.limit !== undefined ? { limit: input.limit } : {}),
+          ...(inputString(input, 'cursor') ? { cursor: inputString(input, 'cursor') } : {}),
+        }),
+        'usage.query',
+      )
+    },
+  }
+}
+
+function timeRange(input: Record<string, unknown>): Record<string, unknown> {
+  const since = parseTimestamp(input.since, 'since')
+  const until = parseTimestamp(input.until, 'until')
+  if (since === undefined) {
+    if (until !== undefined) throw new UsageError('INVALID_ARGUMENT', '--until requires --since')
+    return { kind: inputString(input, 'range') ?? 'last7d' }
+  }
+  if (input.range !== undefined) {
+    throw new UsageError('ARGUMENT_CONFLICT', '--range cannot be combined with --since')
+  }
+  return { kind: 'explicit', start_time_ms: since, end_time_ms: until ?? Date.now() }
+}

package/cli/modules/app.ts

@@ -97,6 +97,7 @@ export function createAppModule(dependencies: AppModuleDependencies = {}): Comma
     lifecycleCommand('stop', 'Stop an installed App'),
     restartCommand(),
     statusCommand(),
+    publishCommand(),
   ]
   return {
     name: 'app',
@@ -458,6 +459,91 @@ function statusCommand(): CommandDefinition {
   }
 }
 
+function publishCommand(): CommandDefinition {
+  return {
+    verb: 'publish',
+    summary: 'Package a directory on the control-panel node into the Zone Repo as an App candidate',
+    description:
+      'Calls control-panel app.publish: packages <local_dir> (a path on the control-panel node; nothing is uploaded) with the AppDoc template, stores PackageMeta and the AppDoc in the Zone Repo/NamedStore, and stages a self-checked PIKG there. The AppDoc is not Owner-signed and no BNS/App DID record is updated, so this is not an authoritative App release.',
+    positionals: [
+      { name: 'local_dir', description: 'Absolute source directory on the control-panel node' },
+    ],
+    options: [
+      {
+        name: 'app-doc',
+        property: 'app_doc',
+        description: 'AppDoc template JSON file (pkg_list entries without pkg_objid)',
+        type: 'string',
+        required: true,
+      },
+      {
+        name: 'app-type',
+        property: 'app_type',
+        description: 'App type; defaults to the template app_type',
+        type: 'string',
+        enum: ['dapp', 'web', 'agent'],
+      },
+    ],
+    inputSchema: {
+      type: 'object',
+      properties: {
+        local_dir: { type: 'string', minLength: 1 },
+        app_doc: { type: 'string', minLength: 1 },
+        app_type: { type: 'string', enum: ['dapp', 'web', 'agent'] },
+      },
+      required: ['local_dir', 'app_doc'],
+      additionalProperties: false,
+    },
+    outputSchema: OBJECT_OUTPUT,
+    resultSchemaVersion: 1,
+    access: { mode: 'fixed', level: 'write' },
+    asyncMode: 'sync',
+    requiresSession: true,
+    examples: [
+      'buckyos app publish /srv/build/demo-web --app-doc ./demo-web.appdoc.json',
+      'buckyos app publish /srv/build/demo-agent --app-doc ./demo-agent.appdoc.json --app-type agent',
+    ],
+    handler: async (ctx, input) => {
+      const localDir = expectString(input, 'local_dir')
+      if (!isAbsolute(localDir)) {
+        throw new UsageError(
+          'INVALID_ARGUMENT',
+          'local_dir must be an absolute path on the control-panel node',
+        )
+      }
+      let appDoc: unknown
+      try {
+        appDoc = JSON.parse(
+          await getHost().readTextFile(resolveFromCwd(ctx, expectString(input, 'app_doc'))),
+        )
+      } catch (error) {
+        throw new UsageError(
+          'INVALID_APP_DOC',
+          `failed to read AppDoc template: ${errorMessage(error)}`,
+        )
+      }
+      if (!isObject(appDoc)) {
+        throw new UsageError('INVALID_APP_DOC', 'AppDoc template must be a JSON object')
+      }
+      const result = expectObject(
+        await callControl(ctx, 'app.publish', {
+          local_dir: localDir,
+          app_doc: appDoc,
+          ...(typeof input.app_type === 'string' ? { app_type: input.app_type } : {}),
+        }),
+        'app.publish response',
+      )
+      const { ok: _ok, ...published } = result
+      return {
+        ...published,
+        publish_status: expectString(result, 'publish_status'),
+        app_doc_signature: 'not-signed',
+        app_did_publication: 'not-published',
+      }
+    },
+  }
+}
+
 async function fetchApp(
   ctx: CommandContext,
   input: Record<string, unknown>,

package/cli/modules/log.ts

@@ -12,6 +12,8 @@ import {
 
 const CONTROL_PANEL = 'control-panel'
 const OBJECT_OUTPUT: JsonSchema = { type: 'object', additionalProperties: true }
+// Stored entry levels (control-panel sys_log_mgr normalize_log_level); WARN is stored as warning.
+const LOG_LEVELS = ['error', 'warning', 'info', 'debug', 'trace']
 
 export interface LogModuleDependencies {
   sleep?: (milliseconds: number, signal: AbortSignal) => Promise<void>
@@ -21,8 +23,40 @@ export interface LogModuleDependencies {
 export function createLogModule(dependencies: LogModuleDependencies = {}): CommandModule {
   return {
     name: 'log',
-    summary: 'Query, follow, and export redacted system logs',
-    commands: [queryCommand(), tailCommand(dependencies), exportCommand(dependencies)],
+    summary: 'List services, query, follow, and export redacted system logs',
+    commands: [
+      servicesCommand(),
+      queryCommand(),
+      tailCommand(dependencies),
+      exportCommand(dependencies),
+    ],
+  }
+}
+
+function servicesCommand(): CommandDefinition {
+  return {
+    verb: 'services',
+    summary: 'List the service IDs that have system logs',
+    inputSchema: { type: 'object', properties: {}, additionalProperties: false },
+    outputSchema: {
+      type: 'object',
+      properties: { services: { type: 'array', items: OBJECT_OUTPUT } },
+      required: ['services'],
+      additionalProperties: false,
+    },
+    resultSchemaVersion: 1,
+    access: { mode: 'fixed', level: 'read' },
+    asyncMode: 'sync',
+    requiresSession: true,
+    examples: ['buckyos log services'],
+    handler: async (ctx) => {
+      const response = expectObject(
+        await callService(ctx, CONTROL_PANEL, 'system.logs.list', {}),
+        'Control Panel log service list',
+      )
+      if (!Array.isArray(response.services)) invalidResponse('log service list')
+      return { services: response.services }
+    },
   }
 }
 
@@ -178,7 +212,9 @@ function filterOptions(plural: boolean) {
     {
       name: plural ? 'services' : 'service',
       property: plural ? 'services' : 'service',
-      description: plural ? 'Comma-separated service IDs' : 'Service ID',
+      description: plural
+        ? 'Comma-separated service IDs (buckyos log services)'
+        : 'Service ID (buckyos log services)',
       type: 'string' as const,
       required: true,
     },
@@ -187,7 +223,11 @@ function filterOptions(plural: boolean) {
       description: 'Exact filename in the service log directory',
       type: 'string' as const,
     },
-    { name: 'level', description: 'Exact normalized log level', type: 'string' as const },
+    {
+      name: 'level',
+      description: `Log level: ${LOG_LEVELS.join(', ')} (warn = warning)`,
+      type: 'string' as const,
+    },
     { name: 'keyword', description: 'Case-insensitive content filter', type: 'string' as const },
     { name: 'since', description: 'RFC 3339 lower time boundary', type: 'string' as const },
     { name: 'until', description: 'RFC 3339 upper time boundary', type: 'string' as const },
@@ -224,7 +264,7 @@ function normalizeFilter(
   return compact({
     services,
     file: inputString(input, 'file'),
-    level: inputString(input, 'level')?.toLowerCase(),
+    level: normalizeLevel(inputString(input, 'level')),
     keyword: inputString(input, 'keyword'),
     since: normalizeLogTime(input, 'since'),
     until: normalizeLogTime(input, 'until'),
@@ -234,6 +274,18 @@ function normalizeFilter(
   }) as Record<string, unknown> & { services: string[] }
 }
 
+function normalizeLevel(value: string | undefined): string | undefined {
+  if (!value) return undefined
+  const level = value.toLowerCase() === 'warn' ? 'warning' : value.toLowerCase()
+  if (!LOG_LEVELS.includes(level)) {
+    throw new UsageError(
+      'INVALID_ARGUMENT',
+      `level must be one of ${LOG_LEVELS.join(', ')} (warn = warning)`,
+    )
+  }
+  return level
+}
+
 function normalizeLogTime(input: Record<string, unknown>, key: string): string | undefined {
   const value = inputString(input, key)
   if (!value) return undefined

package/cli/modules/pikg.ts

@@ -54,6 +54,12 @@ const SHA256_ID = /^sha256:[0-9a-f]{64}$/
 const OBJECT_ID = /^(?:appdoc|pkg):[0-9a-f]{64}$/
 const SAFE_GENERATED_FILE = /^[A-Za-z0-9._-]+$/
 const OBJECT_OUTPUT = { type: 'object' as const, additionalProperties: true }
+const APP_KINDS = ['static-web', 'script', 'docker', 'agent-skills']
+const PATH_KINDS: Record<string, { key: string; category: string; selectorType: string }> = {
+  'static-web': { key: 'web', category: 'web', selectorType: 'static' },
+  script: { key: 'script', category: 'dapp', selectorType: 'single' },
+  'agent-skills': { key: 'agent_skills', category: 'agent_skills', selectorType: 'single' },
+}
 
 export interface DockerImageInfo {
   id: string
@@ -201,7 +207,7 @@ export function createPikgModule(dependencies: PikgModuleDependencies = {}): Com
             name: 'kind',
             description: 'Initial App kind',
             type: 'string',
-            enum: ['static-web', 'script', 'docker'],
+            enum: APP_KINDS,
           },
           {
             name: 'source',
@@ -217,7 +223,7 @@ export function createPikgModule(dependencies: PikgModuleDependencies = {}): Com
             project_dir: { type: 'string', minLength: 1 },
             name: { type: 'string', minLength: 1 },
             owner: { type: 'string', minLength: 1 },
-            kind: { type: 'string', enum: ['static-web', 'script', 'docker'] },
+            kind: { type: 'string', enum: APP_KINDS },
             source: { type: 'string', minLength: 1 },
             version: { type: 'string', minLength: 1 },
             app_did: { type: 'string', minLength: 1 },
@@ -234,6 +240,7 @@ export function createPikgModule(dependencies: PikgModuleDependencies = {}): Com
         examples: [
           'buckyos pikg init .',
           'buckyos --non-interactive pikg init . --owner did:bns:root --kind static-web --source ./web/dist',
+          'buckyos --non-interactive pikg init . --owner did:bns:root --kind agent-skills --source ./skills',
         ],
         handler: async (ctx, input) => await initCommand(ctx, input, docker),
       },
@@ -440,11 +447,11 @@ async function initCommand(
     kind = await requiredPrompt(
       ctx,
       canPrompt,
-      'App kind (static-web/script/docker): ',
+      `App kind (${APP_KINDS.join('/')}): `,
       'kind',
     )
   }
-  if (!['static-web', 'script', 'docker'].includes(kind)) {
+  if (!APP_KINDS.includes(kind)) {
     throw new UsageError('INVALID_APP_KIND', `invalid App kind: ${kind}`)
   }
   let source = optionalInputString(input, 'source')
@@ -474,7 +481,7 @@ async function initCommand(
     sourceValue = { type: 'docker-image', image: source }
     sourceSummary = { type: 'docker-image', image: image.canonicalName, image_id: image.id }
   } else {
-    subpackageKey = kind === 'static-web' ? 'web' : 'script'
+    subpackageKey = PATH_KINDS[kind].key
     const absoluteSource = resolve(projectDir, source)
     const persistedSource = isAbsolute(source)
       ? resolve(source)
@@ -498,9 +505,9 @@ async function initCommand(
     owner,
     author: owner,
     show_name: name,
-    categories: [kind === 'static-web' ? 'web' : 'dapp'],
+    categories: [PATH_KINDS[kind]?.category ?? 'dapp'],
     permissions: [],
-    selector_type: kind === 'static-web' ? 'static' : 'single',
+    selector_type: PATH_KINDS[kind]?.selectorType ?? 'single',
     service_config_tips: {},
   }
   const pikgMeta = {

package/cli/modules/pikg_archive.ts

@@ -136,6 +136,89 @@ export async function gzipFile(source: string, destination: string): Promise<voi
   await getHost().gzipFile(source, destination)
 }
 
+export interface TarFileEntry {
+  path: string
+  executable: boolean
+  bytes: Uint8Array
+}
+
+export async function readTarGz(bytes: Uint8Array, limit: number): Promise<TarFileEntry[]> {
+  const tar = await gunzipBytes(bytes, limit)
+  const decoder = new TextDecoder('utf-8', { fatal: true })
+  const text = (offset: number, length: number) =>
+    decoder.decode(tar.subarray(offset, offset + length)).replace(/\0.*$/s, '')
+  const files: TarFileEntry[] = []
+  const seen = new Set<string>()
+  let offset = 0
+  while (
+    offset + BLOCK_SIZE <= tar.length && tar.subarray(offset, offset + BLOCK_SIZE).some(Boolean)
+  ) {
+    let raw: string
+    let size: number
+    let mode: number
+    try {
+      const prefix = text(offset + 257, 6) === 'ustar' ? text(offset + 345, 155) : ''
+      raw = prefix ? `${prefix}/${text(offset, 100)}` : text(offset, 100)
+      size = Number.parseInt(text(offset + 124, 12).trim() || '0', 8)
+      mode = Number.parseInt(text(offset + 100, 8).trim() || '0', 8)
+    } catch {
+      throw invalidZip('payload', 'tar header is not valid UTF-8')
+    }
+    const type = String.fromCharCode(tar[offset + 156] || 0x30)
+    const path = raw.replace(/^(?:\.\/)+/, '').replace(/\/$/, '')
+    const start = offset + BLOCK_SIZE
+    if (!Number.isSafeInteger(size) || size < 0 || start + size > tar.length) {
+      throw invalidZip('payload', `tar entry is truncated: ${raw}`)
+    }
+    offset = start + Math.ceil(size / BLOCK_SIZE) * BLOCK_SIZE
+    if (type === '5' && (path === '' || path === '.')) continue
+    if (
+      !path || path.startsWith('/') || /^[A-Za-z]:/.test(path) || path.includes('\\') ||
+      path.split('/').some((segment) => !segment || segment === '.' || segment === '..')
+    ) {
+      throw invalidZip('payload', `unsafe tar entry path: ${JSON.stringify(raw)}`)
+    }
+    if (type === '5') continue
+    if (type !== '0') {
+      throw invalidZip('payload', `tar entry is not a regular file or directory: ${path}`)
+    }
+    if (seen.has(path)) throw invalidZip('payload', `duplicate tar entry: ${path}`)
+    seen.add(path)
+    files.push({ path, executable: (mode & 0o111) !== 0, bytes: tar.slice(start, start + size) })
+  }
+  return files
+}
+
+async function gunzipBytes(bytes: Uint8Array, limit: number): Promise<Uint8Array> {
+  const stream = new ReadableStream<Uint8Array>({
+    start(controller) {
+      controller.enqueue(bytes)
+      controller.close()
+    },
+  }).pipeThrough(
+    new DecompressionStream('gzip') as unknown as ReadableWritablePair<Uint8Array, Uint8Array>,
+  )
+  const chunks: Uint8Array[] = []
+  let size = 0
+  try {
+    for await (const chunk of stream) {
+      size += chunk.length
+      if (size > limit) throw invalidZip('limits', 'payload expands beyond the size limit')
+      chunks.push(chunk)
+    }
+  } catch (error) {
+    if (error instanceof ToolError) throw error
+    throw invalidZip('compression', 'payload is not a valid gzip stream')
+  }
+  const result = new Uint8Array(size)
+  let position = 0
+  for (const chunk of chunks) {
+    result.set(chunk, position)
+    position += chunk.length
+  }
+  return result
+}
+
 export async function writeStoredZip(
   destination: string,
   sources: ZipWriteSource[],