@zonease/aiworker-cli 0.12.2 → 0.13.0

package/official-apps/aiworker-hr/src/host-mounted.ts

@@ -0,0 +1,308 @@
+import { Buffer } from 'node:buffer'
+import process from 'node:process'
+
+import { createSoulAppClient } from '@zonease/aiworker-soul-app-sdk'
+
+import { hrReferenceSoulApp, hrSoulAppManifest } from './index'
+
+interface MountContext {
+  brokerUrl?: string
+  hostUrl?: string
+  operatorId?: string | null
+  sessionId?: string | null
+  surface?: {
+    id?: string
+    scope?: string
+  }
+  workerId?: string | null
+  workspaceId?: string | null
+}
+
+interface BrokerSearchResult {
+  items?: Array<Record<string, unknown>>
+}
+
+export function serveHostMounted(port = Number(Bun.env.PORT ?? 0)) {
+  return Bun.serve({
+    async fetch(request) {
+      const url = new URL(request.url)
+      if (url.pathname === '/health') {
+        return Response.json({
+          appId: hrSoulAppManifest.id,
+          mode: 'host-mounted',
+          status: 'ok',
+        })
+      }
+      const tokenError = verifyMountToken(request)
+      if (tokenError)
+        return tokenError
+      if (url.pathname === '/domain') {
+        return Response.json({
+          appId: hrSoulAppManifest.id,
+          capabilities: hrSoulAppManifest.capabilities.map(capability => capability.id),
+          mounted: true,
+          soul: hrSoulAppManifest.soul.id,
+          workspaceTypes: hrSoulAppManifest.workspaceTypes.map(type => type.id),
+        })
+      }
+      if (url.pathname === '/surfaces/routes/hr-home' || url.pathname === '/surfaces/panels/hr-profile-panel') {
+        return Response.json(hrDescriptorSurface(request, url.pathname))
+      }
+      if (url.pathname === '/frames/widgets/hr-people-widget') {
+        return new Response(hrWidgetFrameHtml(request), {
+          headers: { 'content-type': 'text/html; charset=utf-8' },
+        })
+      }
+      if (url.pathname === '/protocol/actions' && request.method === 'POST') {
+        const body = await request.json().catch(() => ({})) as Record<string, unknown>
+        return Response.json(await hrProtocolAction(request, String(body.protocolAction ?? '')))
+      }
+      if (url.pathname === '/protocol/search' && request.method === 'GET') {
+        return Response.json(await hrProtocolSearch(request, url))
+      }
+      if (url.pathname === '/broker/permissions') {
+        const hostUrl = request.headers.get('x-aiworker-host-url') ?? Bun.env.AIWORKER_HOST_URL
+        if (!hostUrl)
+          return Response.json({ appId: hrSoulAppManifest.id, broker: 'not-configured', permissions: [] })
+        const client = createSoulAppClient({ appId: hrSoulAppManifest.id, baseUrl: hostUrl })
+        return Response.json(await client.broker.permissions.list())
+      }
+      if (url.pathname === '/protocol/capabilities') {
+        return Response.json({
+          capabilities: await hrReferenceSoulApp.ui?.capabilities({
+            appId: hrSoulAppManifest.id,
+            permissions: hrSoulAppManifest.permissions,
+          }),
+        })
+      }
+      return Response.json({ error: { code: 'NOT_FOUND', message: `Unknown HR app route: ${url.pathname}` } }, { status: 404 })
+    },
+    hostname: Bun.env.HOST ?? '127.0.0.1',
+    port,
+  })
+}
+
+if (import.meta.main) {
+  const server = serveHostMounted()
+  process.stdout.write(`${JSON.stringify({ appId: hrSoulAppManifest.id, mode: 'host-mounted', url: `http://${server.hostname}:${server.port}` })}\n`)
+}
+
+function verifyMountToken(request: Request): Response | null {
+  const expected = Bun.env.AIWORKER_MOUNT_TOKEN
+  if (!expected)
+    return null
+  const actual = request.headers.get('x-aiworker-mount-token')
+  return actual === expected
+    ? null
+    : Response.json({ error: { code: 'INVALID_MOUNT_TOKEN', message: 'Host mount token is required.' } }, { status: 401 })
+}
+
+function hrDescriptorSurface(request: Request, pathname: string) {
+  const context = readMountContext(request)
+  return {
+    actions: [
+      {
+        id: 'create-profile-review',
+        label: 'Create review',
+        method: 'POST',
+        target: `${context?.brokerUrl ?? '/broker'}/reviews`,
+      },
+    ],
+    appId: hrSoulAppManifest.id,
+    authority: 'soul-app',
+    cache: {
+      freshness: 'non-authoritative',
+    },
+    context: {
+      signed: Boolean(request.headers.get('x-aiworker-mount-signature')),
+      surfaceId: context?.surface?.id ?? null,
+      workspaceId: context?.workspaceId ?? null,
+    },
+    fields: [
+      { label: 'Domain', value: hrSoulAppManifest.soul.domain },
+      { label: 'Workspace types', value: hrSoulAppManifest.workspaceTypes.map(type => type.name).join(', ') },
+      { label: 'Evidence broker', value: hrSoulAppManifest.connectors.required.map(connector => connector.id).join(', ') },
+    ],
+    path: pathname,
+    renderer: 'host-descriptor',
+    status: 'ready',
+    title: pathname.includes('/routes/') ? 'HR Mounted Workbench' : 'People Profile Panel',
+    type: 'aiworker.surface.descriptor.v1',
+  }
+}
+
+function hrWidgetFrameHtml(request: Request): string {
+  const context = readMountContext(request)
+  return [
+    '<!doctype html>',
+    '<html lang="en">',
+    '<head><meta charset="utf-8"><title>HR People Widget</title></head>',
+    '<body>',
+    '<main>',
+    '<h1>People Widget</h1>',
+    `<p data-soul-app-id="${hrSoulAppManifest.id}">Mounted HR frame surface</p>`,
+    `<p data-surface-id="${context?.surface?.id ?? 'unknown'}">Scope ${context?.surface?.scope ?? 'workspace'}</p>`,
+    '</main>',
+    '</body>',
+    '</html>',
+  ].join('')
+}
+
+async function hrProtocolAction(request: Request, protocolAction: string) {
+  if (protocolAction === 'peopleProfiles.create') {
+    const persisted = await persistPeopleProfileDraft(request)
+    if (!persisted.ok)
+      return persisted
+    return {
+      message: 'People profile draft opened by HR app.',
+      ok: true,
+      redirectTo: '/hr/people',
+      refresh: true,
+    }
+  }
+  if (protocolAction === 'people.refresh') {
+    return {
+      message: 'People data refreshed by HR app.',
+      ok: true,
+      refresh: true,
+    }
+  }
+  if (protocolAction === 'drawers.evidence.toggle') {
+    return {
+      message: 'Evidence drawer intent emitted by HR app.',
+      ok: true,
+    }
+  }
+  if (protocolAction === 'settings.open') {
+    return {
+      message: 'HR settings are owned by the HR app.',
+      ok: true,
+    }
+  }
+  return {
+    message: `Unknown HR protocol action: ${protocolAction}`,
+    ok: false,
+  }
+}
+
+async function persistPeopleProfileDraft(request: Request): Promise<{ message: string, ok: false } | { ok: true }> {
+  const context = readMountContext(request)
+  if (!context?.hostUrl)
+    return { ok: true }
+
+  const draftKey = `drafts/people-profile/${context.workspaceId ?? 'app'}`
+  const workspaceRef = context.workspaceId ?? 'app'
+  const client = createSoulAppClient({ appId: hrSoulAppManifest.id, baseUrl: context.hostUrl })
+  try {
+    await client.broker.storage.put(draftKey, {
+      appId: hrSoulAppManifest.id,
+      kind: 'people-profile',
+      source: 'hr-mounted-action',
+      status: 'draft',
+      workspaceId: context.workspaceId ?? null,
+    }, brokerScope(context))
+    await client.broker.search.upsert(draftKey, {
+      kind: 'people-profile',
+      reference: {
+        id: workspaceRef,
+        type: context.workspaceId ? 'workspace' : 'app',
+      },
+      sessionId: context.sessionId ?? null,
+      summary: `HR app-owned people profile draft for workspace ${workspaceRef}.`,
+      title: 'People profile draft',
+      workspaceId: context.workspaceId ?? null,
+    }, brokerScope(context))
+    return { ok: true }
+  }
+  catch (error) {
+    return {
+      message: error instanceof Error ? error.message : String(error),
+      ok: false,
+    }
+  }
+}
+
+async function hrProtocolSearch(request: Request, url: URL) {
+  const query = url.searchParams.get('query') ?? ''
+  const brokerItems = await queryBrokerPeopleProfileSearch(request, query)
+  if (brokerItems?.length) {
+    return {
+      items: brokerItems,
+      providerId: 'peopleProfiles.search',
+    }
+  }
+
+  return {
+    items: [{
+      appId: hrSoulAppManifest.id,
+      authority: 'soul-app' as const,
+      id: 'people-profile-draft',
+      kind: 'people-profile',
+      openAction: {
+        id: 'create-people-profile',
+        input: { query },
+      },
+      status: 'draft',
+      summary: query ? `HR app-owned profile match for ${query}` : 'Open HR profile workspace',
+      title: query ? `People profile: ${query}` : 'People profile draft',
+    }],
+    providerId: 'peopleProfiles.search',
+  }
+}
+
+async function queryBrokerPeopleProfileSearch(request: Request, query: string): Promise<Array<Record<string, unknown>> | null> {
+  const context = readMountContext(request)
+  if (!context?.hostUrl)
+    return null
+
+  const client = createSoulAppClient({ appId: hrSoulAppManifest.id, baseUrl: context.hostUrl })
+  try {
+    const result = await client.broker.search.query(query, brokerScope(context)) as BrokerSearchResult
+    return Array.isArray(result.items) ? result.items : null
+  }
+  catch {
+    return null
+  }
+}
+
+function readMountContext(request: Request): MountContext | null {
+  const payload = request.headers.get('x-aiworker-mount-context')
+  if (!payload)
+    return null
+  try {
+    const parsed = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8')) as unknown
+    if (!isRecord(parsed))
+      return null
+    const surface = isRecord(parsed.surface) ? parsed.surface : null
+    return {
+      brokerUrl: typeof parsed.brokerUrl === 'string' ? parsed.brokerUrl : undefined,
+      hostUrl: request.headers.get('x-aiworker-host-url') ?? undefined,
+      operatorId: typeof parsed.operatorId === 'string' ? parsed.operatorId : null,
+      sessionId: typeof parsed.sessionId === 'string' ? parsed.sessionId : null,
+      surface: surface
+        ? {
+            id: typeof surface.id === 'string' ? surface.id : undefined,
+            scope: typeof surface.scope === 'string' ? surface.scope : undefined,
+          }
+        : undefined,
+      workerId: typeof parsed.workerId === 'string' ? parsed.workerId : null,
+      workspaceId: typeof parsed.workspaceId === 'string' ? parsed.workspaceId : null,
+    }
+  }
+  catch {
+    return null
+  }
+}
+
+function brokerScope(context: MountContext) {
+  return {
+    operatorId: context.operatorId ?? undefined,
+    sessionId: context.sessionId ?? undefined,
+    workerId: context.workerId ?? undefined,
+    workspaceId: context.workspaceId ?? undefined,
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

package/official-apps/aiworker-hr/src/index.ts

@@ -0,0 +1,152 @@
+import type {
+  SoulAppArtifactValidationResult,
+  SoulAppCapability,
+  SoulAppDefinition,
+  SoulAppProtocolResult,
+  SoulAppScopedContext,
+  SoulAppSessionContext,
+} from '@zonease/aiworker-soul-app-sdk'
+
+import { createSoulAppManifest, defineSoulApp, parseNamespacedSoulAppCapabilityId } from '@zonease/aiworker-soul-app-sdk'
+
+import manifestJson from '../soul-app.manifest.json' with { type: 'json' }
+
+export const hrSoulAppManifest = createSoulAppManifest(manifestJson)
+
+export const HR_REFERENCE_APP_BOUNDARY = {
+  hostMountedEntry: './src/host-mounted.ts',
+  packageName: '@zonease/aiworker-hr',
+  primaryWorkbench: 'People/Profile Workbench',
+  standaloneEntry: './src/standalone.ts',
+} as const
+
+export const hrReferenceSoulApp: SoulAppDefinition = defineSoulApp({
+  artifact: {
+    async artifactSchemas() {
+      return hrSoulAppManifest.artifactTypes
+    },
+    async extractMetadata(_context, artifact) {
+      return {
+        appId: hrSoulAppManifest.id,
+        contentRef: artifact.contentRef,
+        kind: artifact.type,
+        lifecycle: artifact.type === 'person-profile' ? 'people-profile' : 'recruiting',
+      }
+    },
+    async validateArtifact(_context, artifact) {
+      return validateArtifactType(artifact.type)
+    },
+  },
+  connector: {
+    async declareConnectorNeeds() {
+      return [
+        ...hrSoulAppManifest.connectors.required,
+        ...hrSoulAppManifest.connectors.optional,
+      ]
+    },
+  },
+  lifecycle: lifecycleHandlers('HR reference app ready.'),
+  manifest: hrSoulAppManifest,
+  review: {
+    async createReviewRubric(_context, artifactType) {
+      return {
+        checks: [
+          `Artifact type ${artifactType} cites source evidence.`,
+          'Missing candidate or employee facts are explicit.',
+          'Human review notes separate risks, next actions, and memory candidates.',
+        ],
+        policyRef: hrSoulAppManifest.artifactTypes.find(type => type.id === artifactType)?.reviewPolicyRef,
+      }
+    },
+    async proposeMemoryCandidate(context, review) {
+      return {
+        evidence: [{
+          appId: context.appId,
+          artifactId: review.artifactId,
+          reviewId: review.reviewId,
+          source: 'hr-reference-app',
+        }],
+        statement: 'Promote reviewed HR evidence handling guidance into the HR Soul namespace.',
+      }
+    },
+  },
+  runtime: {
+    async prepareSessionContext(context, input) {
+      const capability = resolveHrCapability(input.capabilityId)
+      return sessionContext(context, capability, input.workspaceType)
+    },
+    async resolveCapability(_context, input) {
+      return resolveHrCapability(input.capabilityId ?? input.intent)
+    },
+  },
+  ui: {
+    async artifactTypes() {
+      return hrSoulAppManifest.artifactTypes
+    },
+    async capabilities() {
+      return hrSoulAppManifest.capabilities
+    },
+    async ui() {
+      return hrSoulAppManifest.ui
+    },
+    async workspaceTypes() {
+      return hrSoulAppManifest.workspaceTypes
+    },
+  },
+})
+
+function resolveHrCapability(input?: string): SoulAppCapability {
+  const id = normalizeCapabilityId(input) ?? hrSoulAppManifest.capabilities[0]!.id
+  const capability = hrSoulAppManifest.capabilities.find(item => item.id === id)
+  if (!capability)
+    throw new Error(`HR capability not found: ${input}`)
+  return capability
+}
+
+function normalizeCapabilityId(input?: string): string | null {
+  if (!input)
+    return null
+  return parseNamespacedSoulAppCapabilityId(input)?.capabilityId ?? input
+}
+
+function sessionContext(context: SoulAppScopedContext, capability: SoulAppCapability, workspaceType: string): SoulAppSessionContext {
+  return {
+    artifactTypes: capability.artifactTypes,
+    capabilityId: capability.id,
+    contextMarkdown: [
+      '# HR Soul App Context',
+      `App: ${context.appId}`,
+      `Workspace type: ${workspaceType}`,
+      'Use people-profile, candidate-screen, review notes, and source-backed evidence language.',
+    ].join('\n'),
+    promptFragments: [
+      `Use HR capability ${capability.name}.`,
+      'Preserve candidate or employee evidence provenance and mark missing facts.',
+      'Return a reviewable HR business artifact, not a generic chat answer.',
+    ],
+    reviewRubric: [
+      'Evidence is source-backed.',
+      'Risk and missing evidence are separated.',
+      'Next action is concrete for a human HR reviewer.',
+    ],
+  }
+}
+
+function validateArtifactType(type: string): SoulAppArtifactValidationResult {
+  const known = hrSoulAppManifest.artifactTypes.some(item => item.id === type)
+  return {
+    issues: known ? [] : [{ message: `Unknown HR artifact type: ${type}`, severity: 'error' }],
+    ok: known,
+  }
+}
+
+function lifecycleHandlers(message: string) {
+  const ok = async (): Promise<SoulAppProtocolResult> => ({ message, ok: true })
+  return {
+    disable: ok,
+    enable: ok,
+    healthcheck: ok,
+    install: ok,
+    upgrade: ok,
+  }
+}

package/official-apps/aiworker-hr/src/protocol/artifact.ts

@@ -0,0 +1,2 @@
+export const protocolSurface = 'artifact'
+export { hrReferenceSoulApp as soulApp } from '../index'

package/official-apps/aiworker-hr/src/protocol/connectors.ts

@@ -0,0 +1,2 @@
+export const protocolSurface = 'connectors'
+export { hrReferenceSoulApp as soulApp } from '../index'

package/official-apps/aiworker-hr/src/protocol/lifecycle.ts

@@ -0,0 +1,2 @@
+export const protocolSurface = 'lifecycle'
+export { hrReferenceSoulApp as soulApp } from '../index'

package/official-apps/aiworker-hr/src/protocol/review.ts

@@ -0,0 +1,2 @@
+export const protocolSurface = 'review'
+export { hrReferenceSoulApp as soulApp } from '../index'

package/official-apps/aiworker-hr/src/protocol/runtime.ts

@@ -0,0 +1,2 @@
+export const protocolSurface = 'runtime'
+export { hrReferenceSoulApp as soulApp } from '../index'

package/official-apps/aiworker-hr/src/protocol/ui.ts

@@ -0,0 +1,2 @@
+export const protocolSurface = 'ui'
+export { hrReferenceSoulApp as soulApp } from '../index'

package/official-apps/aiworker-hr/src/standalone.ts

@@ -0,0 +1,43 @@
+import process from 'node:process'
+
+import { hrSoulAppManifest } from './index'
+
+export function renderStandaloneHtml(): string {
+  return [
+    '<!doctype html>',
+    '<html lang="en">',
+    '<head><meta charset="utf-8"><title>AIWorker HR</title></head>',
+    `<body data-soul-app-id="${hrSoulAppManifest.id}">`,
+    '<main>',
+    `<h1>${hrSoulAppManifest.name}</h1>`,
+    `<p>${hrSoulAppManifest.description}</p>`,
+    '</main>',
+    '</body>',
+    '</html>',
+  ].join('')
+}
+
+export function serveStandalone(port = Number(Bun.env.PORT ?? 0)) {
+  return Bun.serve({
+    fetch(request) {
+      const url = new URL(request.url)
+      if (url.pathname === '/health') {
+        return Response.json({
+          appId: hrSoulAppManifest.id,
+          mode: 'standalone',
+          status: 'ok',
+        })
+      }
+      return new Response(renderStandaloneHtml(), {
+        headers: { 'content-type': 'text/html; charset=utf-8' },
+      })
+    },
+    hostname: Bun.env.HOST ?? '127.0.0.1',
+    port,
+  })
+}
+
+if (import.meta.main) {
+  const server = serveStandalone()
+  process.stdout.write(`${JSON.stringify({ appId: hrSoulAppManifest.id, mode: 'standalone', url: `http://${server.hostname}:${server.port}` })}\n`)
+}

package/official-apps/aiworker-hr/src/ui/candidate-screen-preview.tsx

@@ -0,0 +1,2 @@
+export const artifactPreviewId = 'candidate-screen'
+export const artifactPreviewLabel = 'Candidate Screen'

package/official-apps/aiworker-hr/src/ui/hr-route.tsx

@@ -0,0 +1 @@
+export const routeId = 'hr-home'

package/official-apps/aiworker-hr/src/ui/people-widget.tsx

@@ -0,0 +1 @@
+export const widgetId = 'hr-people-widget'

package/official-apps/aiworker-hr/src/ui/person-profile-preview.tsx

@@ -0,0 +1,2 @@
+export const artifactPreviewId = 'person-profile'
+export const artifactPreviewLabel = 'Person Profile'

package/official-apps/aiworker-hr/src/ui/profile-panel.tsx

@@ -0,0 +1 @@
+export const panelId = 'hr-profile-panel'

package/official-apps/aiworker-hr/src/ui/review-panel.tsx

@@ -0,0 +1 @@
+export const panelId = 'hr-review-panel'

package/official-apps/aiworker-hr/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "paths": {
+      "@/*": [
+        "./src/*"
+      ]
+    },
+    "types": [
+      "@types/bun"
+    ]
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist"
+  ]
+}

package/official-apps/aiworker-qa/README.md

@@ -0,0 +1,14 @@
+# AIWorker QA Reference Soul App
+
+`@zonease/aiworker-qa` is the reference QA Soul App workspace. It owns the QA
+manifest, protocol handlers, standalone service, Host-mounted service, schemas,
+capabilities, review policy, and release-focused app definition for regression
+matrices, defect evidence, and release gate review.
+
+The app depends on the Soul App SDK only. It does not import Host API, CLI,
+Worker Web private modules, raw DB handles, engine adapters, connector tokens,
+vault internals, or sibling Soul Apps.
+
+The app is intentionally different from HR: QA workspaces are release/test-suite
+oriented, and its primary artifact is a release gate decision with explicit
+test evidence and residual risk.

package/official-apps/aiworker-qa/capabilities/regression-matrix/prompt.md

@@ -0,0 +1,3 @@
+# Regression Matrix
+
+Use AIWorker QA domain evidence to create a reviewable regression-matrix artifact. Keep provenance, missing facts, risks, and next actions explicit.

package/official-apps/aiworker-qa/capabilities/regression-matrix/review.md

@@ -0,0 +1,5 @@
+# Regression Matrix Review Rubric
+
+- Evidence references are present.
+- Missing information is explicit.
+- Risks and next actions are concrete.

package/official-apps/aiworker-qa/capabilities/release-gate/prompt.md

@@ -0,0 +1,3 @@
+# Release Gate
+
+Use AIWorker QA domain evidence to create a reviewable release-gate artifact. Keep provenance, missing facts, risks, and next actions explicit.

package/official-apps/aiworker-qa/capabilities/release-gate/review.md

@@ -0,0 +1,5 @@
+# Release Gate Review Rubric
+
+- Evidence references are present.
+- Missing information is explicit.
+- Risks and next actions are concrete.