alex/headquarter
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
1f2c3dbe2acb0010f1398d03286e5c498154ef33
headquarter/openspec/tasks/tool-definition-manifest.md
T
Alex Blank 3e99e7f197 feat: legacy fallback tests and docs (PR 3) 
- Add test_tool_instances_legacy.py with 8 unit tests:
  - dockerfile definition type builds from template
  - dockerfile build failure raises HTTP 500
  - compose definition type renders template
  - manifest compiler is NOT called for legacy types
  - start_instance legacy/compose/dockerfile types all skip manifest flow
  - start_instance manifest type correctly invokes compiler
- Mark T3.2 and T3.3 tasks complete in OpenSpec
- Add openspec/docs/tool-workshop-guide.md with user guide covering
  definition types, manifest creation workflow, base definitions,
  migration path, and permissions
2026-05-28 14:54:32 +02:00

3.1 KiB
Raw Blame History

Tasks: Tool Definition Manifest System

PR 1: Backend Manifest System

T1.1 Database Migration

  • Create tool_definition_manifests table
  • Add manifest_id, definition_type to tool_types
  • Add manifest_compiled_at, image_tag to tool_instances
  • Data migration: convert pi-agent to manifest

T1.2 Models

  • ToolDefinitionManifest SQLAlchemy model
  • Update ToolType model with manifest relationship
  • Update ToolInstance model with image_tag

T1.3 Manifest Compiler

  • resolve_base() — deep merge base + tool manifest
  • compile_dockerfile() — generate Dockerfile from manifest
  • compile_entrypoint() — generate startup entrypoint script
  • compile_compose() — generate Compose from manifest
  • compute_image_tag() — deterministic hash-based tag
  • resolve_mount_source() — mount source resolution

T1.4 Permission Fixer

  • apply_mount_permissions() — post-start chown/chmod
  • Handle missing root user gracefully
  • Timeout and error reporting

T1.5 API Endpoints

  • POST /tool-definitions — create
  • GET /tool-definitions — list
  • GET /tool-definitions/{id} — get
  • PUT /tool-definitions/{id} — update
  • DELETE /tool-definitions/{id} — delete
  • POST /tool-definitions/{id}/compile — preview

T1.6 Modified Startup Flow

  • Update start_instance to use manifest when definition_type == "manifest"
  • Integrate permission fixer post-start
  • Store image_tag on instance for reuse

T1.7 Tests

  • Unit: manifest compiler (all package managers, base merge)
  • Unit: permission fixer (success, failure, timeout)
  • Unit: mount resolution (all source types)
  • Integration: manifest → build → start → terminal works
  • Integration: legacy tool types still work

PR 2: Frontend Tool Workshop

T2.1 Tool Definitions API Client

  • Add tool definition endpoints to client.ts
  • Type definitions for manifest schema

T2.2 Tool Workshop Page

  • Base image selector (with version dropdown)
  • Package manager editors (apt list, npm list, node version)
  • Script editors (build vs startup, tabbed)
  • Mount schema designer (form table with add/remove)
  • Runtime config (command, working_dir, stdin_open, tty)

T2.3 Live Preview

  • Preview panel showing generated Dockerfile
  • Preview panel showing generated Compose
  • "Compile" button calling API preview endpoint

T2.4 Tool Definitions List

  • Table view of all definitions
  • Create / Edit / Delete actions
  • Base indicator (shows if it's a base definition)

PR 3: Migration & Legacy Fallback

T3.1 Data Migration

  • Alembic migration creating base definition + pi-agent manifest
  • Update existing pi-agent tool_type row

T3.2 Legacy Fallback

  • Ensure definition_type == "legacy" still uses old flow
  • Ensure dockerfile_template / compose_template still work
  • Tests for legacy path

T3.3 Documentation

  • Update API docs
  • Add Tool Workshop user guide
Reference in New Issue View Git Blame Copy Permalink