diff --git a/apps/server/src/ntbs/adapter.ts b/apps/server/src/ntbs/adapter.ts new file mode 100644 index 00000000000..70b3d2fa144 --- /dev/null +++ b/apps/server/src/ntbs/adapter.ts @@ -0,0 +1,77 @@ +import type { ThreadId } from "@t3tools/contracts"; +import * as NTBS from "./lifecycle.ts"; +import { Context, Data, Effect } from "effect"; + +export class ThreadNotFound extends Data.TaggedError("ThreadNotFound") {} + +/** + * Generic error catcher, will be refined later + */ +export class AdapterError extends Data.TaggedError("AdapterError")<{ + readonly reason: string; +}> {} + +export type NTBSResponse = { + readonly type: "answer" | "failure" | "timeout" | "cancellation"; + readonly text: string; +}; + +/** + * Defines the platform-specific operations used by the shared NTBS processor. + * + * The adapter detects duplicate requests, stores lifecycle data, finds that data + * from a T3 thread ID, and posts acknowledgements and responses. + * + * The adapter owns its storage and retention policy. A stored snapshot may + * outlive the original platform message. E.g. a message on Discord gets deleted + * but its still persisted in the original snapshot. + * Verify retention policies. + * + * It does not create T3 threads or interpret T3 events. + */ +export interface NTBSAdapter

{ + /** + * Stores the request before any T3 work begins. + * + * Returns `"duplicate"` if the same platform request was already stored. + */ + readonly accept: ( + event: NTBS.NTBSInput

, + ) => Effect.Effect<"accepted" | "duplicate", AdapterError>; + /** + * Stores a lifecycle state. Does not perform any other business logic. + */ + readonly save: (lifecycleEvent: NTBS.NTBSLifecycle

) => Effect.Effect; + /** + * Posts the working acknowledgement at the response destination, + * described by the event. + * + * Returns the platform's identifier for the posted message. + */ + readonly postAcknowledgement: ( + state: NTBS.ThreadStarted

, + ) => Effect.Effect; + /** + * Posts the final T3 outcome at the response destination described + * by the event. + * + * Returns the platform's idenitifier for the posted message. + * The processor uses that identifier to save `ResponsePosted`. + */ + readonly postResponse: ( + state: NTBS.ThreadStarted

, + response: NTBSResponse, + ) => Effect.Effect; + /** + * Finds the latest lifecycle state associated with a T3 thread. + * + * Fails with `ThreadNotFound` when this adapter has no request associated + * with that thread. + */ + readonly findByThreadId: ( + threadId: ThreadId, + ) => Effect.Effect, ThreadNotFound | AdapterError>; +} + +export const makeNTBSAdapterTag =

(key: string) => + Context.Service>(key); diff --git a/apps/server/src/ntbs/lifecycle.ts b/apps/server/src/ntbs/lifecycle.ts new file mode 100644 index 00000000000..49aaf86d5c2 --- /dev/null +++ b/apps/server/src/ntbs/lifecycle.ts @@ -0,0 +1,51 @@ +import type { ChatAttachment, ThreadId } from "@t3tools/contracts"; + +/** + * Describes the platform-specific data of a + * Non-Turn-Based-Surface. + * + * When receiving an NTBS event (a comment, a message tagging + * a bot, etc) `source` and `responseDestination` hold the details + * necessary to process the what and why. + */ +export type PlatformData = { + source: Source; + responseDestination: ResponseDestination; +}; + +export type NTBSInput

= { + /** + * Each NTBSEvent carries the adapter-defined external data. + * T3 never inspects it. Only the adapter deals with it. + */ + platformData: P; + /** + * The captured source text sent as the first T3 user message. + * Platform independent. + * Must not exceed T3's 120,000-character input limit. + */ + snapshot: string; + /** + * References to attachments stored by T3 and sent with the first user message. + * The processor creates them from attachment data provided by the adapter. + */ + attachments: ReadonlyArray; +}; + +export type ThreadEvent

= NTBSInput

& { + t3Data: { + /** The T3 thread created by the lifecycle event */ + threadId: ThreadId; + }; +}; + +export type ThreadStarted

= ThreadEvent

& { + /** T3 has created the new thread. */ + state: "thread.started"; +}; +export type ResponsePosted

= ThreadEvent

& { + state: "thread.response.posted"; + responseMessageId: string; +}; + +export type NTBSLifecycle

= ThreadStarted

| ResponsePosted

; diff --git a/apps/server/src/ntbs/processor.ts b/apps/server/src/ntbs/processor.ts new file mode 100644 index 00000000000..f9e16769f76 --- /dev/null +++ b/apps/server/src/ntbs/processor.ts @@ -0,0 +1,180 @@ +import { + type ChatAttachment, + type OrchestrationEvent, + type ProjectId, + type ThreadId, +} from "@t3tools/contracts"; +import type * as NTBS from "./lifecycle.ts"; +import { Context, Crypto, Data, Effect } from "effect"; +import type { NTBSAdapter, NTBSResponse } from "./adapter.ts"; +import type { OrchestrationEngineService } from "../orchestration/Services/OrchestrationEngine.ts"; +import type { ProjectionSnapshotQuery } from "../orchestration/Services/ProjectionSnapshotQuery.ts"; +import type { GitWorkflowService } from "../git/GitWorkflowService.ts"; +import type { ProjectSetupScriptRunner } from "../project/ProjectSetupScriptRunner.ts"; + +/* + NTBS architecture: + + 1. Generic NTBS processor: + - Runs the shared workflow for every platform. + - Asks the adapter to detect duplicate input. + - Creates a fresh worktree and T3 thread. + - Saves `ThreadStarted`. + - Starts the first turn with the snapshot and attachments. + - Attempts to post the acknowledgement independently. + - Watches T3 events for completed work. + - Posts the final result through the adapter and saves `ResponsePosted`. + + 2. Platform-specific inbound code: + - Receives raw platform data from Jira, Discord, GitHub, or Teams. + - Applies platform trigger and actor checks. + - Builds `NTBSInput

` and `T3Context`. + - Calls the processor. + + 3. Adapter + - Owns platform storage, duplicate detection, and platform API calls. + - Posts acknowledgements and responses. + - Knows how platform identifiers are represented. + - Knows nothing about creating T3 threads or interpreting T3 events. +*/ + +export type T3Context = { + readonly projectId: ProjectId; + readonly revision: string; +}; + +export type ProcessorEvent

= + | { + readonly source: "adapter"; + readonly event: NTBS.NTBSInput

; + readonly t3Context: T3Context; + } + | { + readonly source: "t3"; + readonly event: OrchestrationEvent; + }; + +export class NTBSProcessorError extends Data.TaggedError("NTBSProcessorError")<{ + reason: string; +}> {} + +export interface NTBSProcessor

{ + /** + * Routes adapter requests and T3 events through the shared NTBS workflow. + * + * Platform requests must already have passed their platform-specific trigger + * and actor checks. The processor does not perform those. + * + * Accepts concurrent requests and applies no queue, concurrency cap + * or backpressure for the time being. This choice can be reviewed later. + */ + readonly process: (event: ProcessorEvent

) => Effect.Effect; + + /** + * Consumes T3 events and passes them to `processT3Event`. + * + * Runs until interrupted by its caller. + * Logs individual processing failures and continues with later events. + */ + readonly subscribeToT3Events: Effect.Effect; +} + +export const makeNTBSProcessorTag =

(key: string) => + Context.Service>(key); + +type NTBSProcessorRequirements = + /* + Dispatches thread creation and turn-start commands. + Provides the T3 event stream used to detect outcomes. + */ + | OrchestrationEngineService + /* + Loads the selected T3 project and reads the completed thread + state and response text. + */ + | ProjectionSnapshotQuery + /* + Creates the isolated branch and worktree for each accepted external request. + */ + | GitWorkflowService + /* + Runs the project setup scripts in the newly created worktree before agent work begins. + */ + | ProjectSetupScriptRunner + /* + Generates unique identifiers for the new thread, message, commands, and worktree branch. + */ + | Crypto.Crypto; + +/** + * Creates an isolated worktree and a new T3 thread. + * + * Does not start a turn, read platform data or call the adapter. + * + * The final title of the thread is generated by T3 after the first turn starts. + */ +declare const createT3Thread: (t3Context: T3Context) => Effect.Effect; + +/** + * Starts the first turn in an existing T3 thread. + */ +declare const startT3Turn: ( + threadId: ThreadId, + snapshot: string, + attachments: ReadonlyArray, +) => Effect.Effect; + +/** + * Handles an external request in this order: + * + * 1. Ask the adapter to accept it and stop if it is a duplicate. + * 2. Create the worktree and T3 thread. + * 3. Record `ThreadStarted`. + * 4. Start the first T3 turn with the snapshot and attachments. + * 5. Attempt to post the acknowledgement independently. + */ +declare const processAcceptedRequest:

( + request: NTBS.NTBSInput

, + t3Context: T3Context, +) => Effect.Effect; + +/** + * Provider runtimes (like Claude Code) emit `turn.completed` events. + * T3 consumes those internally and exposes the resulting session change through a `thread.session-set` event. + * + * Native T3 clients can react by refreshing the thread projection. + * External NTBS adapters do not consume T3 projections automatically, so they must read the thread state themselves. + * + * This function reads the projected thread identified by the session event. + * It returns `null` if the latest turn has not ended. + * Otherwise it returns the response and its type. + */ +declare const resolveT3Outcome: ( + event: Extract, +) => Effect.Effect< + { readonly threadId: ThreadId; readonly response: NTBSResponse } | null, + NTBSProcessorError +>; + +/** + * Handles T3 events that may indicate that a turn has ended. + * + * 1. Ignore events other than `thread.session-set`. + * 2. Find the adapter record by thread ID. + * 3. Stop if no record exists or the response was already posted. + * 4. Resolve the T3 outcome and stop if the turn has not ended. + * 5. Post the response. + * 6. Record `ResponsePosted`. + */ +declare const processT3Event: ( + event: OrchestrationEvent, +) => Effect.Effect; + +/** + * Creates an NTBS processor for one adapter. + * + * Resolves the required T3 services and returns processor operations with no remaining requirements. + */ +export declare const makeNTBSProcessor:

( + adapter: NTBSAdapter

, +) => Effect.Effect, never, NTBSProcessorRequirements>; diff --git a/docs/planning/fixes.md b/docs/planning/fixes.md new file mode 100644 index 00000000000..db893be916f --- /dev/null +++ b/docs/planning/fixes.md @@ -0,0 +1,66 @@ +# NTBS fixes + +This document collects the units of work identified by the adversarial review of the NTBS design. + +## 11. Define the shared thread defaults + +T3 requires an initial title, model selection, runtime mode, and interaction mode when creating a thread. `T3Context` currently provides only the project and revision, so the implementation would otherwise have to invent these choices or make each platform choose them independently. + +Keep `T3Context` limited to `projectId` and `revision`. The shared processor applies the same policy for every platform: + +- Create the thread with T3's default title and let the normal first-turn title generation replace it. +- Use the project's default model selection, falling back to T3's automatic bootstrap model selection. +- Use `full-access` runtime mode. +- Use `default` interaction mode. +- Treat `revision` as the Git ref from which the new isolated worktree starts, and resolve it when creating that worktree. + +Adapters provide the project and revision but do not choose or persist the remaining thread settings in the first implementation. + +## 12. Resolve the response for the correct T3 message + +The processor currently stores only the T3 thread ID and reads the latest turn when looking for the final response. If someone continues that thread from a native T3 client, the latest turn may belong to different work and its answer could be posted back to the original external request. + +Store the ID of the first T3 user message with `ThreadStarted`. Resolve the final response for that specific message instead of reading the latest turn in the thread. Record the corresponding turn ID later when T3 provides it. + +## 13. Archive the T3 thread after posting the response + +Every external request creates a new T3 thread and worktree. Leaving them open after the response has been posted would cause unused threads and worktrees to accumulate. + +After the response has been successfully posted and saved as `ResponsePosted`, archive its T3 thread so the normal T3 cleanup rules can remove the worktree. Treat archival as separate cleanup: if it fails, retry the archival without posting the response again. This can become a configurable retention policy later if a platform needs different behavior. + +## 14. Keep remote adapters in mind + +The current NTBS shape assumes adapters run inside the T3 server and call the processor directly. This works for the initial Jira and GitHub adapters, but the current Discord bot runs as a separate program. + +When Discord is ported, either move its adapter into the server or expose the processor through a network API. Do not choose or implement that transport yet, but avoid making the lifecycle and storage design depend unnecessarily on every adapter sharing the server process. + +## 15. Verify an uncertain response before posting it again + +The adapter may successfully post a response and then stop before saving `ResponsePosted`. On recovery, it must not immediately post the response again. + +First inspect recent messages in the known response destination. Look for a message authored by the adapter, posted in the expected time frame, attached to the expected comment or thread, and containing the expected response. If it is found, save `ResponsePosted` using the existing platform message and continue without posting again. Retry `postResponse` only when that check finds no matching message. + +Each adapter owns the exact comparison because platforms may format, truncate, or split messages differently. + +## 16. Recover missed T3 events after restart + +The processor only receives T3 events emitted while it is running. If T3 finishes work while the processor or server is down, the completion event is missed and the response would never be posted. + +Whenever the processor starts, load every unfinished NTBS record and check its current state in T3. Continue completed work, report failures, and resume waiting for work that is still running. Treat live T3 events as signals to check the current state, not as the only record of what happened. + +This recovery does not require storing an event cursor or replaying the T3 event log. T3's current state and the adapter's unfinished records provide enough information to continue. + +## 17. Handle work that does not finish in time + +The processor currently waits forever for T3 to report that a turn has finished. If the provider hangs or disconnects without producing a completion event, the external platform never receives a final message. + +Check the target turn after 30 minutes: + +- If it is `running` or `starting`, wait another 15 minutes. +- If it is `completed`, retrieve and post its answer. +- If it is in `error`, `interrupted`, or `stopped`, post that failure without automatically rerunning the agent. +- If no turn ever started, retry the turn-start command once when it is safe to repeat. +- If the thread cannot be read because of a temporary failure, retry the status check rather than the T3 work. +- If the thread no longer exists, post an error and stop. + +If the turn is still running after 45 minutes, post that T3 is still working and include a link to the T3 thread. Then close the external response flow. A later answer remains available in T3 but is not posted automatically to the external platform. diff --git a/docs/planning/ideas.md b/docs/planning/ideas.md new file mode 100644 index 00000000000..8b4bbdda2e6 --- /dev/null +++ b/docs/planning/ideas.md @@ -0,0 +1,27 @@ +# NTBS ideas + +## Keep the shared lifecycle small + +There is a tradeoff between recovering every possible interruption and keeping the first implementation simple. A saved `RequestAccepted` state could recover the rare case where the server receives a request but stops before creating its T3 thread. Doing that safely would also require planned thread IDs, startup searches, retries, and duplicate handling. + +For now, the shared lifecycle should begin with `ThreadStarted`. The processor should save it as soon as the basic T3 thread exists, before slower preparation begins. A request can be lost if the server stops before that point, but the missing acknowledgement makes the failure visible and the user can send the request again. + +A stronger recovery system can be added later if real usage requires it. Each adapter could inspect recent messages on its platform, find requests that have no corresponding T3 thread, and submit them again. This belongs to the adapter because Jira, GitHub, Discord, and Teams provide different ways to read their recent messages. + +## Remove acknowledgement from the shared lifecycle + +The acknowledgement is platform feedback, such as a "working on it" message. It should not be a required stage in the shared NTBS lifecycle because failing to post it, or failing to save its message ID, must not prevent the processor from representing and posting the final response. + +Remove `ThreadStartedAcknowledgement` from the lifecycle and remove `acknowledgementMessageId` from `ResponseAvailable` and `ResponsePosted`. The adapter may still post an acknowledgement and retain its identifier in its own platform-specific storage when needed. When posting the final response, the adapter can reply to the acknowledgement or fall back to the original source message according to the platform's capabilities. + +The shared sequence becomes: + +`Create the T3 thread → record ThreadStarted → start the work and attempt the acknowledgement independently` + +The processor does not use acknowledgement success as a condition for continuing. Posting may happen alongside the start of T3 work, and an adapter may retry a failed acknowledgement, but the final answer always remains tied to the original response destination. If a platform benefits from replying to the acknowledgement, its adapter can use the identifier stored in its own data without adding that dependency to the shared lifecycle. + +## Remove fork-specific provenance after the NTBS migration + +Keep `SourceChannel`, `SourceRef`, `sourceHint`, `originSource`, and related fork-specific provenance out of the NTBS design. Adapters already retain the platform data needed to connect external messages with T3 work. + +Once every external platform has moved to NTBS, remove these fields and the old integration logic that depends on them. diff --git a/docs/planning/ntbs-architecture.md b/docs/planning/ntbs-architecture.md new file mode 100644 index 00000000000..b47cf90e0bd --- /dev/null +++ b/docs/planning/ntbs-architecture.md @@ -0,0 +1,178 @@ +# NTBS architecture + +**Status:** exploratory planning + +This document defines the boundary between T3 and adapters for non-turn-based surfaces such as Jira, GitHub, Discord, and Teams. It explains which system retains which information and the shared path from an external event to a T3 result and back to the external platform. + +## Problem + +T3 clients are built around T3 data views such as threads, diffs, and projects. External platforms know none of those concepts. They only know their own messages, comments, conversations, and identifiers. + +An adapter therefore cannot rely on an external platform to retain T3 state, and T3 cannot infer where a later result belongs from its own thread data alone. The adapter must retain the link between its platform's event and the T3 work created from it. + +## Shared model + +An adapter receives a platform event, applies the trigger rules, captures the source snapshot, and creates a new T3 thread. It retains the platform identifiers and the T3 identifiers created from that event. + +The adapter sends an acknowledgement to the external platform. When T3 reports the thread's final outcome, the adapter uses its retained record to post the final answer, failure, timeout, or cancellation in the correct place. + +T3 remains independent of the platform that produced the event. It owns its threads, messages, turns, execution state, worktrees, and branches. The adapter owns platform authentication, event delivery, source snapshots, platform identifiers, response placement, and platform-specific rendering. + +The adapter keeps the full record for its platform. T3 does not receive or interpret platform data. The adapter makes sure the same platform message does not start T3 work twice, creates the snapshot, and asks T3 to start work. T3 receives the snapshot, returns the new thread, message, and turn IDs, and later reports the final outcome. The adapter adds those T3 values to its own record and posts the result on its platform. + +Storage and retention are adapter implementation details, not architecture decisions. Platform-specific edge cases, such as a source item being deleted or closed while T3 is working, also belong to the adapter implementation phase. + +## Passing T3 context + +An incoming platform event carries both platform data and the T3 context needed to start work, such as the project, revision, and execution context. The adapter forwards that T3 context to T3 when it creates the new thread. + +`NtbsEvent` does not retain the project, revision, or execution context as lifecycle data. Once T3 creates the thread, T3 owns that information. Keeping copies in `NtbsEvent` would require the adapter to keep them in sync with T3. + +## Receiving T3 outcomes + +Adapters subscribe to T3's event log, like other T3 consumers. After T3 starts a thread, `NtbsEvent` contains its turn ID. When the adapter receives the final outcome for that turn from the event log, it uses the same `NtbsEvent` to post the result on the external platform. + +## Event lifecycle + +Starting from an external event, this happens: + +1. The adapter accepts an external event that matches a trigger. It creates an adapter record containing the source identifiers, response destination, and captured snapshot. +2. The adapter asks T3 to create a new thread from that snapshot. +3. T3 creates the thread, user message, and turn. The adapter adds those IDs to its record. +4. The adapter posts the acknowledgement and adds its message ID to the record. +5. T3 produces the final answer, failure, timeout, or cancellation for that turn. +6. The adapter finds the record from the T3 IDs, posts the final message at its stored response destination, and adds the final-message ID to the record. + +## Adapter record + +Before it asks T3 to create a thread, the adapter record contains: + +- the adapter's platform data; +- the captured source snapshot as a string; + +After T3 creates the thread, the adapter adds the T3 thread, user-message, and turn IDs. + +After it posts the acknowledgement and final response, the adapter adds their message IDs. + +The event retains the accepted source event, the new T3 thread it starts, and the messages the adapter sends for that thread. + +`NtbsEvent` is a TypeScript pattern for adapter code, not a shared storage format. Each adapter defines, validates, and stores its own platform data. + +```ts +/** All data that is specific to the external platform. */ +type PlatformData = { + /** Information about the inbound event. */ + source: Source; + /** Information about where replies belong. */ + responseDestination: ResponseDestination; +}; + +/** + * Tracks the lifecycle of external inbound events, such as comments or messages, that trigger T3 work. + * External applications have no relationship to T3, and vice versa. The adapter relates events in one to the other. + */ +type NtbsEvent

> = + | NtbsEventAccepted

+ | NtbsEventThreadStarted

+ | NtbsEventAcknowledgementPosted

+ | NtbsEventOutcomeAvailable

+ | NtbsEventResponsePosted

; + +type NtbsEventBase

> = { + /** Adapter-defined data for the external platform. T3 does not inspect it. */ + platformData: P; + /** The captured source text used to create T3's first user message. */ + snapshot: string; +}; + +type NtbsEventAccepted

> = NtbsEventBase

& { + /** The adapter has accepted the inbound event but has not started T3 work. */ + state: "accepted"; +}; + +type NtbsEventWithThread

> = NtbsEventBase

& { + /** The T3 IDs created after the adapter starts work. */ + t3: { + /** The T3 thread created from the source event. */ + threadId: string; + /** The first T3 user message created from the snapshot. */ + userMessageId: string; + /** The T3 turn started from that message. */ + turnId: string; + }; +}; + +type NtbsEventThreadStarted

> = NtbsEventWithThread

& { + /** T3 has created the new thread from the source snapshot. */ + state: "threadStarted"; +}; + +type NtbsEventWithAcknowledgement

> = + NtbsEventWithThread

& { + /** The external acknowledgement message posted by the adapter. */ + acknowledgementMessageId: string; + }; + +type NtbsEventAcknowledgementPosted

> = + NtbsEventWithAcknowledgement

& { + /** The adapter has posted the acknowledgement. */ + state: "acknowledgementPosted"; + }; + +type NtbsEventOutcomeAvailable

> = + NtbsEventWithAcknowledgement

& { + /** T3 has produced a final outcome for the turn. */ + state: "outcomeAvailable"; + }; + +type NtbsEventResponsePosted

> = + NtbsEventWithAcknowledgement

& { + /** The adapter has posted T3's final response. */ + state: "responsePosted"; + /** The external final message posted by the adapter. */ + finalMessageId: string; + }; +``` + +TODO: Define error and retry lifecycle states when adapter behaviour is tested. + +## Jira example + +A user adds top-level Jira comment `10401` on issue `T3-123`: `@agent investigate the failed build`. The adapter accepts source event `jira-event-1`, version `1`, and stores this record before asking T3 to do anything: + +```ts +{ + state: "accepted", + platformData: { + source: { + eventId: "jira-event-1", + version: "1", + contextId: "T3-123", + messageId: "10401", + }, + responseDestination: { + contextId: "T3-123", + parentMessageId: "10401", + }, + }, + snapshot: "@agent investigate the failed build", +} +``` + +When T3 creates the work, the adapter adds its IDs: + +```ts +state: "threadStarted", +t3: { + threadId: "thread-1", + userMessageId: "message-1", + turnId: "turn-1", +} +``` + +The adapter posts an acknowledgement as a reply to Jira comment `10401`, changes the state to `"acknowledgementPosted"`, and adds `acknowledgementMessageId: "10402"`. When T3 produces the final result for `turn-1`, the state becomes `"outcomeAvailable"`. The adapter then posts another reply to comment `10401`, changes the state to `"responsePosted"`, and adds `finalMessageId: "10403"`. + +## Related documents + +- [ntbs.md](./ntbs.md) records the overall scope and agreed decisions. +- [ntbs-event-processing.md](./ntbs-event-processing.md) defines inbound triggers and outbound messages on each platform. diff --git a/docs/planning/ntbs-event-processing.md b/docs/planning/ntbs-event-processing.md new file mode 100644 index 00000000000..22391a340d9 --- /dev/null +++ b/docs/planning/ntbs-event-processing.md @@ -0,0 +1,124 @@ +# NTBS event processing + +**Status:** exploratory planning + +This document defines how events arriving from non-turn-based surfaces are classified and converted into T3 work. It focuses on which events start new T3 threads, which events are ignored, and how independently started threads are correlated with their external events and responses. + +T3 clients are built around T3 data views (projections): threads, diffs, and projects. + +External NTBSs like Jira, Discord, or GitHub know nothing about that: they have only limited capabilities for sending and receiving messages. + +The UX on these platforms has to be thoroughly scoped, and adapters to these platforms have to be extended to retain the information needed to connect T3 events to Jira, Discord, GitHub, or Teams events. + +## Inbound event processing + +### Core rule + +An external event starts a new T3 thread when the adapter recognizes it as one of the trigger forms defined below. Each triggering event creates a new T3 thread. NTBS does not explicitly target, continue, steer, or modify an existing T3 thread. + +The event is captured together with the source snapshot used to construct the first user message. The adapter must distinguish a source event from delivery attempts. Retrying or redelivering the same source event must not create another T3 thread. + +### Adapter storage + +For each inbound event, the adapter retains: + +- the source event ID and version, to avoid handling the same event twice; +- the source context and message or comment IDs, so it knows where the event came from; +- the captured source snapshot; +- the T3 thread, user-message, and turn IDs created from the event. + +### Platform triggers + +The following source interactions start a new thread: + +#### Jira + +- A top-level comment mentioning the agent. +- A reply mentioning the agent. +- A comment edit that adds the agent mention to a comment that previously did not invoke the agent. +- An edit to a comment that already invoked the agent does not trigger a new thread merely because its content changed. A new turn requires a new explicit invocation under the edited comment. + +#### GitHub + +- An issue or pull request comment mentioning the agent. +- A pull-request review comment or reply mentioning the agent. +- A comment edit that adds the agent mention to a comment that previously did not invoke the agent. +- An edit to a comment that already invoked the agent does not trigger a new thread merely because its content changed. A new turn requires a new explicit invocation under the edited comment. + +#### Discord + +- A human message mentioning the configured agent user. +- A human reply to an agent-authored message. +- A message edit that adds the configured agent mention to a message that previously did not invoke the agent. +- Editing a message that already invoked the agent does not start another thread merely because its content changed; a new turn requires a new explicit invocation. + +### Processing a trigger + +When a source interaction matches one of the triggers above, the adapter deduplicates the source event and captures the source snapshot used for the new thread. TODO: define the source event identity and idempotency rules, including late and out-of-order deliveries. + +T3 then starts a new thread from that event and snapshot. A thread already running for the same external interaction does not delay, absorb, continue, or modify the new thread. + +### Events that do not trigger work + +- Edits to a comment that already invoked the agent, including edits that change its content, unless the edited comment contains a new explicit invocation. +- Duplicate or already-accepted deliveries do not create another thread. TODO: define the stable event identity and idempotency rules, including late and out-of-order deliveries. + +Events that do not match one of the triggers above are ignored. Whether adapters retain them for deduplication, audit, or external-state projection is a separate concern. + +### Concurrent turns + +Multiple events from the same external interaction may create T3 threads at the same time. Each thread produces an answer for its own triggering event and sends that answer to the exact response destination associated with that event. Threads may finish in any order; completion order does not change where their answers are sent. + +### Consequences + +- Each event has isolated T3 context; a thread does not inherit the conversation history of another event. +- Each response must retain the exact destination associated with its triggering event. +- Capturing the source snapshot supports reproducibility, but may increase input size, latency, and model cost. +- High-volume external interactions may create many T3 threads and increase storage and discovery noise. + +### Summary + +- An invocation creates an independent T3 thread; it does not target or continue an existing thread. +- Multiple events from the same external interaction may create concurrent threads. +- Each thread produces its own answer, routed to the exact response destination associated with its originating event. +- Duplicate or already-accepted deliveries do not create another thread. TODO: define stable event identity and idempotency rules. + +## Outbound response processing + +Outbound processing adds the acknowledgement and final-outcome message IDs, together with whether each message was posted. + +### Agreed decisions + +Only the acknowledgement and the final answer, failure, timeout, or cancellation are rendered on the external platform. All other T3 events remain internal. + +Each inbound event creates an immediate outbound acknowledgement. When its T3 thread ends, the adapter sends the final answer, failure, timeout, or cancellation as a new message after that acknowledgement, in the platform's native conversation scope. + +#### Response format + +Acknowledgements and final messages are text. Adapters use the platform's Markdown-like formatting, including fenced code snippets when useful. + +T3 does not use interactive controls, permission requests, or multiple-choice prompts on external platforms. Any question is written as ordinary text. + +#### Delivery failures + +The adapter posts the result or error as the final message. If delivery fails for a recoverable reason, it retries; otherwise the original working message remains without a follow-up, and the user may start a new request. + +#### Message identifiers and placement + +Each adapter defines how these identifiers and message relationships map to its platform: + +##### Jira + +The adapter retains the issue ID or key, invoking comment ID, root comment ID, acknowledgement comment ID, and outcome comment ID. It posts the acknowledgement and outcome as separate replies to the same root comment. + +##### GitHub + +The adapter retains the repository, pull-request number, invoking comment ID, root review-comment ID when the invocation is in a review thread, acknowledgement message ID, and outcome message ID. In a review thread, the acknowledgement and outcome both reply to the root review comment. For ordinary issue or pull-request comments, they are separate timeline comments on the pull request. + +##### Discord + +The adapter retains the thread or channel ID, invoking message ID, acknowledgement message ID, and outcome message ID. The acknowledgement replies to the invoking message, and the outcome replies to the acknowledgement. + +##### Teams + +The adapter retains the team and channel or chat ID, root conversation-message ID, invoking message ID, acknowledgement message ID, and outcome message ID. The acknowledgement and outcome are separate replies in the same root conversation. diff --git a/docs/planning/ntbs-plan.md b/docs/planning/ntbs-plan.md new file mode 100644 index 00000000000..802de7c5bde --- /dev/null +++ b/docs/planning/ntbs-plan.md @@ -0,0 +1,63 @@ +# NTBS implementation plan + +**Status:** exploratory planning + +## 1. Understand the existing mechanics + +Read the orchestration command definitions, the orchestration engine service, and the WebSocket turn-start handling to understand how T3 creates threads, prepares worktrees, starts turns, persists events, and exposes those events to consumers. + +Then follow the current Jira path from the webhook route and payload parser through the Jira bridge, delivery store, and Jira API client. This provides concrete examples of inbound event handling, platform-owned persistence, T3 command dispatch, acknowledgement delivery, outcome detection, and outbound response placement. + +The current Jira bridge is a reference, not the desired architecture. It contains platform-independent behavior that should move into the shared NTBS implementation, and it currently reuses existing threads instead of creating a new thread for every accepted event. + +## 2. Build the platform-agnostic NTBS implementation + +Create `apps/server/src/ntbs` for the shared lifecycle model, adapter contract, and workflow service. + +First, extract the existing create-thread, prepare-worktree, and start-turn mechanic from the WebSocket handler into a reusable orchestration service. Both native T3 clients and NTBS workflows should call this service so thread creation behaves consistently regardless of where the request originated. + +Define an adapter contract that leaves platform data opaque to the shared workflow. Each adapter supplies persistence, duplicate prevention, acknowledgement delivery, final-response delivery, and the platform-specific data needed to place those messages. + +Implement the shared workflow: + +1. Accept the snapshot, T3 context, and opaque platform data from an adapter. +2. Persist the accepted lifecycle state before starting T3 work. +3. Create a new T3 thread and worktree, start its first turn, and retain the resulting T3 identifiers. +4. Ask the adapter to post the acknowledgement and retain its platform message identifier. +5. Consume T3 events, including replay after a restart, and identify the final outcome for the recorded work. +6. Load the final assistant text or failure information and ask the adapter to post the final message. +7. Persist every lifecycle transition so interrupted processing can resume safely. + +Confirm when the T3 turn ID becomes available during this work. The current command path knows the thread and user-message IDs immediately but discovers the turn ID later. The implementation and lifecycle types must represent that sequence accurately. + +Test the shared workflow with an in-memory adapter implementation before connecting it to a real platform. The tests should cover successful completion, failure, duplicate delivery, restart recovery, and concurrent events. + +## 3. Port Jira onto the shared implementation + +Keep Jira webhook verification, payload parsing, trigger recognition, Jira identifiers, and Jira API calls inside the Jira adapter. + +Replace the shared workflow currently embedded in the Jira bridge with an implementation of the NTBS adapter contract. Adapt the Jira delivery store to persist the NTBS lifecycle together with Jira-specific source and response-destination data. + +Change Jira processing so every accepted event creates a new T3 thread. Preserve the agreed outbound behavior: post an acknowledgement for the invoking comment, then post the final answer, failure, timeout, or cancellation as a separate reply in the same Jira comment scope. + +Update the Jira tests to prove trigger handling, duplicate prevention, lifecycle recovery, new-thread creation, acknowledgement placement, final-response placement, and concurrent invocations. + +# Notes + +In `packages/contracts/src/orchestration.ts` we can find the schema `ThreadTurnStartBootstrapCreateThread`. + +The schema wants: + +- `projectId` (project should be inferred by discord/jira/etc) +- `title` (generated somewhere) +- `modelSelection` (some model) +- `runtimeMode` (permissions) +- `interactionMode` (apparently default vs plan) +- `branch` (git branch?) +- `worktreePath` (where is it on filesystem) + +It is then used by the + +`ThreadTurnStartBootstrap` which has some optional data for running setup script, preparing worktrees which is then used by + +`ThreadTurnStartCommand` and `ClientThreadTurnStartCommand` (essentially the same type) diff --git a/docs/planning/ntbs.md b/docs/planning/ntbs.md new file mode 100644 index 00000000000..67b2f3f2298 --- /dev/null +++ b/docs/planning/ntbs.md @@ -0,0 +1,70 @@ +# Non-turn-based surfaces + +**Status:** exploratory planning + +## Overview + +T3 currently models interaction primarily as a conversation between one user and an agent. A user submits a message, the agent runs a turn, and T3 presents the resulting conversation and runtime state through clients that understand the full T3 model. + +Non-turn-based surfaces (NTBS) such as Discord, Jira, Teams, GitHub issues, and pull requests do not share those assumptions. They are independently owned collaboration systems where: + +- several people may interact with the same external object; +- messages, comments, and object state may be edited or deleted after T3 first observes them; +- objects may be closed, reopened, moved, locked, or otherwise changed outside T3; +- events may arrive late, more than once, or after T3 has been offline; +- the platform can render only a small part of the state and activity available in a native T3 client. + +The problem is to define how these surfaces participate in T3 without creating a second domain model beside T3's existing one. The existing T3 event log remains the source of truth for T3 state. NTBS support should reuse existing T3 commands, events, and state where possible, while platform adapters translate between T3 and each platform's native concepts. + +This requires a shared contract that answers several questions consistently across platforms: + +- how an external interaction is identified and related to its T3 threads; +- which T3 commands an adapter may issue in response to an external event; +- which T3 events and state an adapter may use to render a response on the external platform; +- how later edits, deletions, multiple participants, retries, and replay affect event handling and response rendering; +- what an adapter does when the external platform cannot represent a T3 event or response; + +The integration protocol should expose only the T3 commands and state needed by these adapters. Adapters should be able to obtain an initial state and then receive subsequent changes. Platform adapters should remain responsible for authentication, source-event translation, transport, and rendering—not for defining their own conversation semantics. + +## Scope of this document + +This document defines the protocol-level relationship between T3 and non-turn-based surfaces. It covers event processing and trigger rules, thread creation, interaction identity, lifecycle, client state, cursors, and adapter behavior. Detailed decisions may be developed in companion planning documents, but remain part of this document's scope. + +Implementation is out of scope for this planning stage. + +## Proposal: A triggering event creates a new thread + +Each event that matches a trigger creates a new T3 thread from the event and its captured source snapshot; the detailed trigger, processing, concurrency, and response-routing rules are defined in [ntbs-event-processing.md](./ntbs-event-processing.md). + +## Agreed decisions + +### Which external messages or state changes trigger an agent turn, and which are ignored or recorded without starting work? + +The platform-specific trigger forms, ignored events, thread creation, and response routing are defined in [ntbs-event-processing.md](./ntbs-event-processing.md). + +### What identifies the same external interaction for correlation and projection? + +- Jira: the issue key or immutable issue ID. Comments and replies are events within that issue. +- Discord: the thread ID. The thread is the interaction. +- GitHub: the repository and pull-request number. Issue comments, review comments, and replies are events within that pull request; the triggering comment and any diff context belong to the individual event. +- Teams: unresolved. The likely scope is the conversation or reply-chain ID, with each message as its own event. + +### When does the adapter capture the source snapshot relative to receiving a trigger and creating the T3 thread? + +The adapter captures the source snapshot while processing the trigger, before creating the T3 thread. The new thread uses that captured snapshot. + +### How does T3 prevent repeated delivery of the same source event from creating multiple threads? + +Each adapter derives an idempotency key from the platform’s source-event identity and version. The adapter stores that key with the T3 thread created for the event. If the same key is delivered again, the adapter reuses the existing record and does not create another thread. A later edit or distinct source event receives a different key and may create a new thread. The exact event identity, versioning, and retention rules are platform-specific and remain to be defined. + +### How are concurrent NTBS threads isolated without an event queue? + +Each NTBS-triggered T3 thread receives its own worktree and branch before provider execution begins. Threads from the same external interaction can therefore run concurrently without sharing a mutable checkout or requiring an event queue. + +### How are completion, failure, timeout, and cancellation reported for an external event? + +They use the same response destination as the triggering event. Normal completion returns the agent’s answer; failure, timeout, or cancellation returns a response that explicitly reports the outcome and, where available, its reason. These outcomes do not create a separate external lifecycle or target a different thread. + +### How does T3 associate a thread's outcome with the external event that created it, and where does the adapter post that outcome? + +Each source event has a unique event ID. T3 stores a correlation record linking that event ID to the T3 thread, user message or turn, and exact response destination. When the turn ends, the adapter uses that record to post the answer or outcome back to the originating source.