Skip to content

refactor: C1 move-only — seven-layer source tree - #1311

Draft
gewenyu99 wants to merge 279 commits into
mainfrom
posthog/functional-c1-move
Draft

gewenyu99 wants to merge 279 commits into
mainfrom
posthog/functional-c1-move

Conversation

@gewenyu99

@gewenyu99 gewenyu99 commented Sep 23, 2026 •

Copy link
Copy Markdown
Collaborator

Problem

Release C's source layout was spread across src/ui/tui, src/lib and src/steps. Programs imported each other, and program tests sat in one shared folder.

Change

Every move in Release C, with no change in behavior:

  • Seven layers: env, shared, agent, programs, tui, headless, cli.
  • The skill factory moves to programs/shared, events-audit to audit/events, and integration detection to detection/. No program imports another.
  • Program tests move into <id>/__tests__.
  • The MCP client writers move to shared/mcp-clients.
  • Each program's TUI gets its own folder under tui/programs/<id>/, with CODEOWNERS.
  • The task stream and the legacy adapter move to cli/, and CLI steering to shared/.

Checks

  • Typecheck, lint, 3,434 unit tests and the arch test pass.
  • Local nine-program snapshot sweep: eight programs complete with exit 0. self-driving stops at the "Connect GitHub" gate because local PostHog has no GitHub App.

Created with PostHog Desktop

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Store authentication, detection, and composition for a single program invocation. Record actual finished agent results separately from projected progress while preserving existing result order.

Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Move scan consent and cleanup registration into UI-free shared leaves. Decouple package-manager file operations from CLI setup and assert the full runProgram import closure.

Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Own artifact watchers and CI inference auth in programs, enforce composition gates, and clean run-installed skills on every failed path.

Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Include status history in fixed-route frame dedupe and rewrite the early outro result when the integration reaches keep-skills.

Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Forward the self-driving connection decision from the legacy session and map the refactored source aliases in Jest.

Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Document callable agent and program contracts, development CI invocation, outcomes, cancellation, and current headless limits.

Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Move Learn and Tips deck selection to the TUI, keep watcher updates behind callback and structural source contracts, and put cross-surface lifecycle enums in shared modules. Shrink the architecture allowlist by 29 edges while preserving program and TUI behavior.

Generated-By: PostHog Desktop

Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
… tests

- The file-watcher tests record calls on a spy instead of a store, and
  drop the deleted-file case, which the capture-once test already makes.
- The store test settles a minimal result without a snapshot fixture.
- Preflight keeps the backup-fail abort as its own test and checks the
  org level on the managed-conflict override instead of a second row. It
  drops the warnings-before-settings call order.
- The run-definition tests share one detected-source fixture.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
The retry test's runAgent spy already reads each attempt's config, so
it asserts scanReport: 'defer' there. This replaces the separate
end-to-end scan-report test and its yara-hooks mock.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Takes the trimmed B2 design wherever B3 only carried older B2 code: the
run-program-agent adapter is one function with no inferenceAuth or
deferSkillCleanupCommit option, keeps B3's run host, completion context,
GitHub gate state and ui-threaded authenticate, and the runners, tui-host
and the composed-step test drop those options. tui-host reads the CI bearer
through B2's lazy closure and commits run skills after the walk. The fault
probe uses B2's createCiGatewayAuth. The adapter and detection tests start
from B2's trimmed files plus B3's own tests; the detection retry test keeps
the two small helpers it needs. The integration prompt helper passes the run
host, the GitHub gate test expects runProgram's single message, and
posthog-integration/source-maps/warehouse keep B3's host effects on B2's
smaller effects port. The programs README now documents settledRuns and
diagnostics, activeNotebookUrl, noAgentWorkflow for every no-agent program,
the entry without test-only exports, and the healthCheck flag. One stale
allowlist row is removed.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…erence

Kept B4's rewritten agent, runner and programs READMEs, and took the trimmed
B2 contracts where they conflict: the programs entry table drops the
test-only policy re-exports, ProgramInput loses mcp, and the agent README
keeps B3's failed-run skill cleanup bullet and now counts eleven entry
names, including TASK_OUTCOMES_KEY. developer-interfaces.md now describes
settledRuns and diagnostics instead of final progress, names noAgentWorkflow
in place of the MCP port, drops the duplicate-runId and throwing-run-definition
rejections, and points both reference hosts at the wizard-workbench harness.
The programs README lists the new run order, with flags, run definition and
refresh before the file watchers.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…move

Brings the trimmed B2 into C1 and lands its changes at the new layer paths. The legacy adapter takes the trimmed runProgramAgent and keeps C1's run host (info and spinner instead of uploadEnvironmentVariables), and posthog-integration keeps C1's in-program env upload without the effects B2 dropped. The two closure tests become B2's single one with C1's src/tui, src/headless and src/cli paths. event-plan-watcher.test.ts and the TUI pricing copy stay deleted, and audit-counts.test.tsx moves to src/tui/__tests__. The allowlist drops four run-program-agent rows that no longer fire.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…again

The legacy adapter runs runHealthGate and runSettingsGate inline, as it
did at the B2 move base, so preflight.ts, its test and its lazy entry
leave the callable host's diff.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
@gewenyu99 gewenyu99 changed the title refactor: C1 move files into the seven-layer tree refactor: C1 move-only — seven-layer source tree Sep 24, 2026
Move program routing out of the agent:
- PROGRAM_BINDINGS and resolveProgramBinding go to src/programs/binding.ts.
- The flag experiments move from src/agent/runner/switchboard/flags to
  src/programs/experiments, with their tests.
- The program-axis commandments go to src/programs/commandments.ts, and
  the switchboard telemetry to src/programs/binding-telemetry.ts.
- The switchboard and variant-gating tests move to src/programs.
- DEFAULT_AGENT_BINDING, in src/agent/default-binding.ts, is the route
  standalone callers pass.

RunConfig drops switchboard. The caller passes what it already resolved:
programCommandments, stageOverrides, seededTasksEnabled and
binding.roleBindings. The orchestrator reads the role routes and the
stage and seeded-task policy from them. Pi assembles the supplied
commandments on both sequences, and Anthropic on task runs. Anthropic's
linear run looked guidance up by the run label, which names no program,
so it still gets none. The agent's resolveBinding and resolveHarness take
the base binding and the flag route as data.

Behavior is unchanged. For every program, across 22 flag and CLI cases,
in dev, production and cloud-surface builds, the resolved binding, trace,
role routes, stage overrides, seeded-task gate and commandments match the
previous code.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
runProgram now runs an existing program: the caller passes the run
definition it built from the ProgramConfig, and a `program` field with
the config's tools, flow, excluded task types, audit ledger and seed,
event plan file, AI requirement and post-auth gates. The legacy adapter
fills both from programConfig, as B1's adapter did.

The runtime registry, the run-definition resolver, the session-free
integration and self-driving recipes, the strategy dispatch, the
integration effects, the no-agent workflow and the composition
connector go. No existing program reached them through the adapter:
no-agent programs never call runProgramAgent, and the TUI runs
self-driving's integration child itself. Post-auth gates stay, as one
awaitPostAuthGates capability. The program configs and the
program-registry return to the B2 move base; audit and events-audit
declare their seed checks instead of writing them from their recipes.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
resolveHarness and resolveRoleHarness move from switchboard/harness.ts
to switchboard/resolve-harness.ts, so harness.ts holds only the
registry. The three-step middleware chain becomes straight-line code
with the same precedence: binding, then the flag route, then the
dev-build CLI model and harness overrides. The traces and log line are
unchanged.

HARNESS_RUNS_TASKS records which backends implement runTask, and the
sequence capability clamp reads it through harnessRunsTasks instead of
asking the live registry. Both backends implement runTask, so the clamp
decides the same way. A registry test keeps the table in step with
HARNESS_OPTIONS. The DEFAULT_BINDING alias goes, and the sequence
resolver reads DEFAULT_AGENT_BINDING.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
The abort-case folds, import reorders, dropped re-exports and comments in
ai-observability, metrics, mcp-analytics, migration, replay-vision,
revenue-analytics and web-analytics-doctor go back to the B2 move base.
TaskStreamPush keeps its WizardStore type and loses only the event-plan
watcher, which runProgram owns now, so its store row returns to
known-violations.json.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
resolveProgramBinding now resolves the sequence itself, so programs own
the whole binding precedence. The agent keeps the harness axis. The
middleware chain becomes straight-line code with the same order: the
composed clamp, the dev-build CLI override, the runTask capability
clamp, the flag route, the sequence experiment, then the base binding.
The traces and log lines are unchanged.

The agent's switchboard keeps the registries, resolveHarness,
resolveRoleHarness and harnessRunsTasks. It drops resolveBinding,
resolveSequence, runChain, and the flagSequence and orchestratorFlagOn
context fields, which only programs read. @agent exports harnessRunsTasks
beside resolveHarness in place of resolveBinding.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Both B2 versions only reordered the code, dropped its comments and
widened a type parameter; the callable host needs neither change.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…ntracts

The agent-signal check joins the run-definition test, the failed-run and
mid-run drain cleanups share one table, and the commit and
deferSkillCommit cases share one test.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
B2 already carries the binding, experiments and harness-resolver moves,
so the merge keeps B2's tree.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Takes B2's host-only runProgram wherever B3 only carried older B2 code. The
run-program-agent adapter builds input.run and input.program from the
ProgramConfig, runs the health and settings gates inline and answers post-auth
gates through awaitPostAuthGates. It keeps B3's run host, completion context
and ui-threaded authenticate, drops the workflow connector and the GitHub
confirm, and takes its programs helpers from the @programs entry, so its four
allowlist rows go. The per-program files take B2's shape with B3's cuts: no
deck or CLI option imports, narrow session types, host effects for warnings and
env upload, and runProgramId on the composed integration step. The
posthog-integration and self-driving hooks read frameworkContext and installDir
from the run's session, since hooks get the completion context. Audit builds
its run with skillRunDefinition. The task stream keeps B3's structural source.
The tests B2 deleted stay deleted, the GitHub gate test goes with the confirm,
and the audit bridge test supplies its seed checks. The programs README
describes the host-only design.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…erence

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…move

Bring in B2's cut to the callable host and the B3/B4 follow-ups. The deleted
preflight, runtime registry, recipe resolution and their tests stay deleted,
including the source-maps run adapter test C1 had edited. The legacy adapter
lands at src/cli/runners with B2's inline gates and C1's info/spinner host.
The restored posthog-integration run calls its own upload step, as C1 moved
it. The adapter's four programs rows leave the allowlist, and the docs point
at src/cli/runners.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Move src/programs/run-agent-legacy.ts to src/lib/runners/run-program-agent.ts
with its content unchanged, the path B3 gives it. Its relative imports now use
the @programs alias, its importers point at the new path, and the path
references in comments and the agent READMEs follow it. The adapter test keeps
its name and path, src/programs/__tests__/run-agent-legacy.test.ts, as it does
in B3.

known-violations.json trades the adapter's old edges for its new ones: the
adapter now sits on the CLI surface and reaches ten programs modules directly,
and the posthog-integration program imports it back. B3 removes those edges.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Bring in the adapter move to src/lib/runners/run-program-agent.ts. B2's
adapter changes land on the new path, its @programs imports replace the
relative ones, and known-violations.json lists the moved adapter's edges.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Set the tree to B1's, then declare the new surfaces with their final names,
paths and signatures, taken from B3 at 50fe9e4 with the bodies removed.

- src/programs/run-program.ts: ProgramOverrides, WizardFlagSnapshot,
  ProgramSettings, ProgramInput, ProgramOptions, ProgramRunOutcome, and a
  runProgram that throws "runProgram: not implemented".
- src/programs/program-store.ts: the progress, diagnostic, invocation-data
  and settled-run types, and ProgramStore's public methods, each throwing.
- src/programs/credentials.ts: ResolvedProgramCredentials,
  CredentialsProvider, and createPosthogInferenceAuthProvider, throwing.
- src/programs/host-capabilities.ts: ProgramCiHost and ProgramRunHost, with
  AuthProjection in authenticate.ts and ProgramCompletionContext in
  program-run.ts.
- The programs entry exports runProgram and createPosthogInferenceAuthProvider
  as lazy loaders, and the type entry exports the new types.
- The agent declares InferenceAuthProvider, the collectTranscript,
  requestRemark and prompt run-definition fields, RunConfig.scanReport,
  RunInput.inferenceAuth (optional until B3 supplies it),
  RunSnapshot.transcriptTail, and the activity progress event, which the UI
  reducer ignores.

Nothing calls the shell: the adapter, the CLI and every doc stay as B1 has
them, and no tests are added.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Record the B1 adapter move and the B2 surface shell as merged. B3 already
holds the full implementation of both, so its tree stays as it was.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
Set every Markdown file to its version at the B2 shell head, so the docs
PR carries every doc change. src/programs/README.md, which B3 added, is
removed here. The e2e-tests READMEs stay deleted with the jest suite they
describe.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…erence

Record the restacked B3, which now leaves every doc change to B4. B4
already holds the final docs and code, so its tree stays as it was.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
…move

Bring in the restacked B stack. B4's tree is unchanged, so C1's tree
stays as it was.

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
@gewenyu99
gewenyu99 changed the base branch from posthog/functional-b4-api-reference to main September 25, 2026 15:16
Rebuilt on main after Release B landed. Moves only: the seven-layer tree,
program boundaries (skill factory in programs/shared, events-audit under
audit/, integration detection in detection/, program tests in their
folders), MCP client writers in shared/, per-program TUI folders under
tui/programs/<id>/ with CODEOWNERS, and the runner-side moves (task
stream and legacy adapter to cli/, login to lib/, headless-mode and CLI
steering to shared/, self-driving pricing into the program).

Generated-By: PostHog Desktop
Task-Id: d14e92bb-6ee1-49b5-8502-39cb80079589
@gewenyu99
gewenyu99 force-pushed the posthog/functional-c1-move branch from 1617519 to ea1e28d Compare September 27, 2026 15:24
@gewenyu99
gewenyu99 added this pull request to stack #1372 September 27, 2026 15:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant