openAgent

1# Message Shape
2 
3Problem:
4 
5- stored messages need enough data to replay and resume a session later
6- prompt hooks often just want to append a synthetic user/assistant message
7- today that means faking ids, timestamps, and request metadata
8 
9## Option 1: Two Message Shapes
10 
11Keep `User` / `Assistant` for stored history, but clean them up.
12 
13```ts
14type User = {
15  role: "user"
16  time: { created: number }
17  request: {
18    agent: string
19    model: ModelRef
20    variant?: string
21    format?: OutputFormat
22    system?: string
23    tools?: Record<string, boolean>
24  }
25}
26 
27type Assistant = {
28  role: "assistant"
29  run: { agent: string; model: ModelRef; path: { cwd: string; root: string } }
30  usage: { cost: number; tokens: Tokens }
31  result: { finish?: string; error?: Error; structured?: unknown; kind: "reply" | "summary" }
32}
33```
34 
35Add a separate transient `PromptMessage` for prompt surgery.
36 
37```ts
38type PromptMessage = {
39  role: "user" | "assistant"
40  parts: PromptPart[]
41}
42```
43 
44Plugin hook example:
45 
46```ts
47prompt.push({
48  role: "user",
49  parts: [{ type: "text", text: "Summarize the tool output above and continue." }],
50})
51```
52 
53Tradeoff: prompt hooks get easy lightweight messages, but there are now two message shapes.
54 
55## Option 2: Prompt Mutators
56 
57Keep `User` / `Assistant` as the stored history model.
58 
59Prompt hooks do not build messages directly. The runtime gives them prompt mutators.
60 
61```ts
62type PromptEditor = {
63  append(input: { role: "user" | "assistant"; parts: PromptPart[] }): void
64  prepend(input: { role: "user" | "assistant"; parts: PromptPart[] }): void
65  appendTo(target: "last-user" | "last-assistant", parts: PromptPart[]): void
66  insertAfter(messageID: string, input: { role: "user" | "assistant"; parts: PromptPart[] }): void
67  insertBefore(messageID: string, input: { role: "user" | "assistant"; parts: PromptPart[] }): void
68}
69```
70 
71Plugin hook examples:
72 
73```ts
74prompt.append({
75  role: "user",
76  parts: [{ type: "text", text: "Summarize the tool output above and continue." }],
77})
78```
79 
80```ts
81prompt.appendTo("last-user", [{ type: "text", text: BUILD_SWITCH }])
82```
83 
84Tradeoff: avoids a second full message type and avoids fake ids/timestamps, but moves more magic into the hook API.
85 
86## Option 3: Separate Turn State
87 
88Move execution settings out of `User` and into a separate turn/request object.
89 
90```ts
91type Turn = {
92  id: string
93  request: {
94    agent: string
95    model: ModelRef
96    variant?: string
97    format?: OutputFormat
98    system?: string
99    tools?: Record<string, boolean>
100  }
101}
102 
103type User = {
104  role: "user"
105  turnID: string
106  time: { created: number }
107}
108 
109type Assistant = {
110  role: "assistant"
111  turnID: string
112  usage: { cost: number; tokens: Tokens }
113  result: { finish?: string; error?: Error; structured?: unknown; kind: "reply" | "summary" }
114}
115```
116 
117Examples:
118 
119```ts
120const turn = {
121  request: {
122    agent: "build",
123    model: { providerID: "openai", modelID: "gpt-5" },
124  },
125}
126```
127 
128```ts
129const msg = {
130  role: "user",
131  turnID: turn.id,
132  parts: [{ type: "text", text: "Summarize the tool output above and continue." }],
133}
134```
135 
136Tradeoff: stored messages get much smaller and cleaner, but replay now has to join messages with turn state and prompt hooks still need a way to pick which turn they belong to.
137