{"_id":"@bensigo/plato-orchestration","name":"@bensigo/plato-orchestration","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@bensigo/plato-orchestration","version":"0.1.0","type":"module","publishConfig":{"access":"public"},"exports":{".":{"types":"./dist/src/index.d.ts","import":"./dist/src/index.js","default":"./dist/src/index.js"}},"main":"./dist/src/index.js","types":"./dist/src/index.d.ts","devDependencies":{"@types/node":"^25.6.0","oxlint":"^1.60.0","vitest":"^4.1.4"},"scripts":{"build":"tsc --project tsconfig.json","dev":"echo 'orchestration dev not wired yet'","lint":"oxlint .","test":"vitest run --dir test","typecheck":"tsc --project tsconfig.json --noEmit"},"_id":"@bensigo/plato-orchestration@0.1.0","description":"`@bensigo/plato-orchestration` owns Plato's agent-agnostic orchestration contracts.","_integrity":"sha512-9Yd1udllrUCoULzHfn2hWfrWR/mA6Iw6s/YoC8QVNHiC8B7QfA8nEzk/los2WXqe7snnn2n3AkHUvEozN3WIsQ==","_resolved":"/private/var/folders/8r/cpk3gflx5cv3hys1x7nvkhwc0000gn/T/225459545d70783e397bffb44433b19a/bensigo-plato-orchestration-0.1.0.tgz","_from":"file:bensigo-plato-orchestration-0.1.0.tgz","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-9Yd1udllrUCoULzHfn2hWfrWR/mA6Iw6s/YoC8QVNHiC8B7QfA8nEzk/los2WXqe7snnn2n3AkHUvEozN3WIsQ==","shasum":"9e0dbfdf408a91934cc3f4cda263aacf79bfa69c","tarball":"https://registry.npmjs.org/@bensigo/plato-orchestration/-/plato-orchestration-0.1.0.tgz","fileCount":10,"unpackedSize":93827,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQD0zjsgeCpfmvj/uEHwfB0V6inqp9LHtD7B+ZTmAYg+NQIhANeRbZ7nDVqv2BwIkBmMuF5Ed8+RJoBccfAaRli9llFE"}]},"_npmUser":{"name":"bensigo","email":"egweybensigo@gmail.com"},"directories":{},"maintainers":[{"name":"bensigo","email":"egweybensigo@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/plato-orchestration_0.1.0_1777302514961_0.4351819122576164"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-27T15:08:34.847Z","0.1.0":"2026-04-27T15:08:35.093Z","modified":"2026-04-27T15:08:35.328Z"},"maintainers":[{"name":"bensigo","email":"egweybensigo@gmail.com"}],"description":"`@bensigo/plato-orchestration` owns Plato's agent-agnostic orchestration contracts.","readme":"# Plato Orchestrator\n\n`@bensigo/plato-orchestration` owns Plato's agent-agnostic orchestration contracts.\n\nThis package is intentionally not tied to Codex. It defines the product-level\nlanguage for tasks, task graphs, events, and agent runtimes so Plato can route\nwork to Codex today and other agents later without changing upstream callers.\n\n## Boundary\n\n- Plato orchestration contracts live here.\n- Agent-specific execution details live in adapter packages.\n- `@bensigo/plato-codex-runner` is the first adapter behind this boundary.\n- MCP and other caller-facing surfaces should depend on this package, not on a\n  concrete runner implementation.\n- `OrchestrationProductSurface` defines stable `plato.*` operation descriptors\n  and JSON-friendly envelopes that CLI/MCP adapters can expose.\n- Worker tool harnesses can provide a neutral `OrchestrationToolHarnessCatalog`;\n  plan validation rejects planned `allowedToolNames` that are not in the\n  supplied catalog.\n- `plato.plan_task_graph` is read-only. It can accept either an already-authored\n  `OrchestrationTaskDecompositionPlan` for validation or a top-level\n  `OrchestrationTaskPlanningInput` brief. Briefs are expanded by the\n  deterministic planner in `src/plan.ts`; the planner does not call LLMs or\n  start runtime tasks.\n\n## Runtime Registration\n\nRuntime bootstrap code should compose concrete agent adapters behind\n`TaskOrchestrationService`:\n\n```ts\nconst orchestration = new TaskOrchestrationService({\n  defaultRuntimeId: \"codex\",\n  runtimes: [codexRuntime],\n});\n```\n\nIn the current product surface, `apps/plato-cli/src/bootstrap.ts` creates the\nCodex adapter and registers it this way. CLI and MCP handlers receive the\nresulting orchestration service as their neutral client, so handler code does\nnot depend on Codex-specific runner internals.\n\n## Planning Preflight\n\n`createTaskDecompositionPlan` turns a top-level task brief into a reviewable\n`OrchestrationTaskDecompositionPlan` before execution. The generated plan\ncontains three deterministic children:\n\n- preflight and contract discovery, with read-only workspace and contract tools;\n- scoped implementation, with Context7 lookup requirements, declared write\n  boundaries, dependencies, and verification commands;\n- verification, review, push, and pull-request handoff, marked approval-gated\n  because it may use external publishing tools.\n\nThe planner classifies each top-level brief into a conservative task template\nbefore choosing default write scopes, verification commands, and acceptance\ncriteria. The current templates cover CLI/MCP adapter work, backend services,\ndocumentation, frontend applications, and infrastructure. Caller-supplied\n`writeScopePaths`, `verificationCommands`, and `acceptanceCriteria` are\npreserved and augmented by the selected template; when no write scope is\nprovided, the template supplies a narrower default than the whole workspace.\n\nThe product surface immediately validates generated plans with\n`validateTaskDecompositionPlan`. Use\n`createValidatedGraphInputFromDecompositionPlan` or\n`plato.validate_task_graph_plan` to convert a reviewed decomposition plan into\nexecutable graph input; invalid plans return validation issues and no graph\ninput. `plato.create_task_graph` remains the lower-level execution operation for\nalready-prepared graph inputs.\n\nFor the default delegated execution path, `plato.delegate_task` accepts a\ntop-level task brief, generates the decomposition plan, validates it, and starts\nthe worker graph only when validation succeeds. The response includes the plan\nand validation result alongside the graph snapshot when execution starts.\n\nPlan validation also checks that documentation requirements carry usable\nContext7 evidence. A requirement must include a Context7 source with a summary\nand version or `checkedAt` freshness marker, or an explicit Context7 gap that\nexplains why the lookup could not be completed. The deterministic planner uses\nan explicit preflight gap so generated plans stay valid before a worker has\nperformed live documentation lookup.\n\nAllowed tools must match the declared execution scope. Write tools such as\n`apply_patch` require writable paths and cannot be placed on low-risk read-only\ntasks, while publishing tools such as `git.push` and `github.open_pr` require\napproval-gated children.\n\n## Review Snapshots\n\n`src/review.ts` provides pure snapshot builders for plan and graph review UX.\n`buildOrchestrationPlanReviewSnapshot` takes an\n`OrchestrationTaskDecompositionPlan` plus its\n`OrchestrationPlanValidationResult` and summarizes validation failures,\nwarnings, worker write boundaries, dependencies, verification requirements, and\napproval-gated children.\n\n`buildOrchestrationGraphReviewSnapshot` takes an\n`OrchestrationTaskGraphSnapshot` and optional\n`OrchestrationTaskGraphResultSnapshot` to summarize worker state, runtime\nidentity, result classification, and final synthesis readiness. Synthesis is\nreported as `not_ready` until the neutral parent synthesis record exists, and\n`ready` once that record is present.\n\n## Result and Synthesis Substrate\n\nThe orchestration boundary already has the neutral M30 result shape. Worker\noutputs are represented by `OrchestrationTaskResultRecord`, parent outcomes by\n`OrchestrationSynthesisRecord`, and graph inspection by\n`OrchestrationTaskGraphResultSnapshot`. Classifications are intentionally small\nand product-facing: `completed`, `partial`, `conflicted`, and `failed`.\n\n`plato.get_task_graph_results` exposes those records to CLI/MCP callers without\nrequiring knowledge of the backend runtime. When a runtime supports graph result\nreconciliation, neutral result inspection asks it to backfill missing terminal\nchild results and syntheses before returning the snapshot. Events can also carry\nresult and synthesis identifiers so callers can correlate collection and\nsynthesis activity with graph lifecycle events.\n\nThe M30 product slice should therefore wire runtime collection, reconciliation,\nand parent synthesis behind these contracts rather than introduce new surface\narea. A reviewable slice should collect one durable result per terminal child\ntask, create the parent synthesis only after every child has a result, and keep\nthe classification visible through graph result inspection.\n\n## Development Notes\n\n- Run tests with `pnpm --filter @bensigo/plato-orchestration test`.\n- Run type-checking with `pnpm --filter @bensigo/plato-orchestration typecheck`.\n","readmeFilename":"README.md","_rev":"1-04280b6d6c6d5340f0bf559498f6cd5d"}