use std::{
collections::BTreeSet,
sync::{Arc, Weak},
time::Duration,
};
use nachalnik::{
Block, BoxError, Capability, Config, Content, ContextId, ContextItem, ContextKind,
ContextState, Delta, Event, Kernel, OutputSink, Tool, ToolCall, ToolCallId, ToolOutput,
ToolSpec, async_trait, selectors::Selector,
};
use parking_lot::Mutex;
use serde_json::{Value, json};
use crate::ui::thousands;
const HEARTBEAT: Duration = Duration::from_millis(120);
const GLIMPSE: usize = 48;
pub fn install(kernel: &Kernel) -> Arc<Kernel> {
let anchor = Arc::new(kernel.clone());
let reach = Reach(Arc::downgrade(&anchor));
let pinned = Arc::new(Mutex::new(BTreeSet::new()));
kernel.add_tool(Arc::new(Introspect {
reach: reach.clone(),
pinned: pinned.clone(),
}));
kernel.add_tool(Arc::new(Amend {
reach,
pinned,
journal: Mutex::new(Journal::default()),
}));
anchor
}
#[derive(Clone)]
struct Reach(Weak<Kernel>);
impl Reach {
fn kernel(&self) -> Result<Arc<Kernel>, BoxError> {
self.0.upgrade().ok_or_else(|| {
"this session is over; there is nothing left to look at or change".into()
})
}
}
pub struct Introspect {
reach: Reach,
pinned: Pinned,
}
type Pinned = Arc<Mutex<BTreeSet<ContextId>>>;
#[async_trait]
impl Tool for Introspect {
fn spec(&self) -> ToolSpec {
ToolSpec::new(
"introspect",
"reads your own state, so you can check it before you act on it. `look` lists every \
item in your context - what it is, what it costs, whether it is going into the next \
request and why not if it is not - and with `ids` reads any of them in full, block \
by block, including what you were thinking when you produced them. `budget` is what \
the next request costs against what there is, what the last one really cost, and \
which items are the expensive ones - read it before deciding what to give up. \
`request` shows the request you are about to send, message by message, with what the \
projector left out and what it repaired. `draft` answers the conversation on a \
throwaway copy and shows you what you would say *before* you say it, so you can \
check your answer against your context and fix either. `fork` puts a question to a \
copy of yourself on a copy of your context, optionally with some items left out - \
for weighing an approach, or asking whether a piece of context is what is leading \
you astray. A fork has no tools: it can think, not act. `amend` is the tool that \
changes any of this.",
)
.with_schema(json!({
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": ["look", "budget", "request", "draft", "fork"],
},
"ids": {
"type": "array",
"items": { "type": "integer" },
"description": "look: read these items in full instead of listing all of them",
},
"question": {
"type": "string",
"description": "fork: what to ask the copy",
},
"without": {
"type": "array",
"items": { "type": "integer" },
"description": "fork: item ids the copy does not get to see",
},
},
"required": ["action"],
}))
.with_capabilities([Capability::Custom("introspect".into())])
.with_output_limit(32_000)
}
async fn invoke(&self, call: &ToolCall, output: OutputSink) -> Result<ToolOutput, BoxError> {
let kernel = self.reach.kernel()?;
match action(&call.args)? {
"look" => Ok(ToolOutput::new(look(&kernel, &ids(&call.args, "ids")))),
"budget" => Ok(ToolOutput::new(budget(&kernel, &self.pinned.lock()))),
"request" => Ok(ToolOutput::new(request(&kernel))),
"draft" => branch(&kernel, None, &[], &output).await,
"fork" => {
let Some(question) = call.args["question"].as_str() else {
return Ok(ToolOutput::error(
"`fork` needs a `question` to put to the copy; `draft` is the one that \
just carries on the conversation",
));
};
branch(
&kernel,
Some(question),
&ids(&call.args, "without"),
&output,
)
.await
}
other => Ok(ToolOutput::error(unknown(
other,
&["look", "budget", "request", "draft", "fork"],
))),
}
}
}
fn look(kernel: &Kernel, ids: &[ContextId]) -> String {
let items = kernel.items();
if !ids.is_empty() {
return ids
.iter()
.map(|id| full(&items, *id))
.collect::<Vec<_>>()
.join("\n");
}
let budget = kernel.budget();
let (withheld, theirs) =
kernel.with_context(|context| (context.tokens_withheld(), context.undo_len()));
let mut out = format!(
"{} items · {} of them go into the next request\n\
~{} tokens going{}, ~{} withheld\n\
{} change(s) in the person's own undo stack, which is theirs; `amend undo` walks back \
what you did\n\n\
{:>4} {:<10} {:<18} {:>8} what it is\n",
items.len(),
items.iter().filter(|item| item.is_projected()).count(),
thousands(budget.used()),
budget
.limit
.map(|limit| format!(
" of {} ({}%)",
thousands(limit),
(budget.fraction_used().unwrap_or_default() * 100.0).round() as usize
))
.unwrap_or_default(),
thousands(withheld),
theirs,
"id",
"state",
"kind",
"tokens",
);
for item in &items {
out.push_str(&format!(
"{:>4} {:<10} {:<18} {:>8} {}\n",
item.id.0,
item.state.to_string(),
item.kind.name(),
thousands(item.tokens),
row(item),
));
}
out.push_str(
"\n`look` with `ids` reads any of these in full, including the reasoning recorded on an \
assistant turn.\n",
);
out
}
fn row(item: &ContextItem) -> String {
let glimpsed = glimpse(&item.content.to_text());
let mut said = match glimpsed.is_empty() {
true => item.label.clone(),
false => format!("{}: {glimpsed}", item.label),
};
if matches!(item.kind, ContextKind::AssistantMessage { .. }) {
let calls = item.calls().count();
if calls != 0 {
said.push_str(&format!(" [{calls} call(s)]"));
}
if item.thinking().next().is_some() {
said.push_str(" [+reasoning]");
}
if let Some(blocks) = item.content.as_blocks() {
said.push_str(&format!(" [{} ordered block(s)]", blocks.len()));
}
}
if let Some(note) = &item.note {
said.push_str(&format!(" · {note}"));
}
said
}
fn full(items: &[Arc<ContextItem>], id: ContextId) -> String {
let Some(item) = items.iter().find(|item| item.id == id) else {
return format!("[{id}] there is no such item\n");
};
let mut out = format!(
"[{}] {} · {} · from {} · {} · {} tokens\n",
item.id,
item.label,
item.kind.name(),
item.source,
item.state,
thousands(item.tokens),
);
if let Some(because) = &item.included_because {
out.push_str(&format!(" it is here because: {because}\n"));
}
if let Some(note) = &item.note {
out.push_str(&format!(" it is {} because: {note}\n", item.state));
}
if !item.meta.is_null() {
out.push_str(&format!(" attached: {}\n", item.meta));
}
if let Some(blocks) = item.content.as_blocks() {
out.push_str(&format!(" --- {} block(s), in order ---\n", blocks.len()));
for (at, block) in blocks.iter().enumerate() {
let said = match block {
Block::Call(call) => format!("{}({})", call.tool, call.args),
_ => block
.part()
.map(|part| part.content.to_text().into_owned())
.unwrap_or_default(),
};
let signed = match block.extra().is_null() {
true => "",
false => " (signed)",
};
out.push_str(&format!(" [{at}] {}{signed}: {said}\n", block.name()));
}
return out;
}
if let Some(reasoning) = item.reasoning() {
out.push_str(&format!(" --- reasoning ---\n{}\n", reasoning.to_text()));
}
out.push_str(&format!(" --- content ---\n{}\n", item.content.to_text()));
out
}
fn budget(kernel: &Kernel, mine: &BTreeSet<ContextId>) -> String {
let budget = kernel.budget();
let withheld = kernel.with_context(|context| context.tokens_withheld());
let room = match budget.limit {
Some(limit) => format!(
" of {} ({}% full, ~{} left)",
thousands(limit),
(budget.fraction_used().unwrap_or_default() * 100.0).round() as usize,
thousands(limit.saturating_sub(budget.used())),
),
None => ", against a limit this provider does not report".to_owned(),
};
let mut out = format!(
"the next request is ~{} tokens{room}\n {} in the context, {} in the tool definitions\n\
~{} tokens are being held back - excluded, archived, or elided to a marker\n",
thousands(budget.used()),
thousands(budget.context_tokens),
thousands(budget.tool_tokens),
thousands(withheld),
);
match budget.reported {
Some(usage) => out.push_str(&format!(
"the last request really cost {} in / {} out, as the provider counted it\n",
thousands(usage.input_tokens.unwrap_or_default() as usize),
thousands(usage.output_tokens.unwrap_or_default() as usize),
)),
None => out.push_str(
"nothing has been charged for yet, so the figures above are only an estimate\n",
),
}
if let Some(learned) = kernel.counter().calibration() {
out.push_str(&match learned.observations {
0 => "the estimate has not been checked against a real request yet; treat it as a floor\n"
.to_owned(),
seen => format!(
"the estimate is corrected by x{:.2}, learned from {seen} request(s)\n",
learned.scale
),
});
}
let going: BTreeSet<ContextId> = kernel.project().included.into_iter().collect();
let mut costly: Vec<_> = kernel
.items()
.into_iter()
.filter(|item| going.contains(&item.id) && item.state.sends_content())
.collect();
costly.sort_by_key(|item| std::cmp::Reverse(item.tokens));
costly.truncate(10);
if costly.is_empty() {
return out;
}
out.push_str(&format!(
"\nthe {} most expensive item(s) actually going into it:\n{:>4} {:<10} {:<18} {:>8} {:>8} what it is\n",
costly.len(),
"id",
"state",
"kind",
"tokens",
"if all go",
));
let mut running = 0;
for item in &costly {
running += item.tokens;
let whose = match protected(item, mine, None) {
Some(_) => " · not yours",
None => "",
};
out.push_str(&format!(
"{:>4} {:<10} {:<18} {:>8} {:>8} {}{whose}\n",
item.id.0,
item.state.to_string(),
item.kind.name(),
thousands(item.tokens),
thousands(running),
glimpse(&format!("{}: {}", item.label, item.content.to_text())),
));
}
out.push_str(
"\nthe fifth column is what eliding everything down to that row would save, give or take \
what the markers cost. Eliding leaves a marker in place, so a tool result still answers \
the call that asked for it; excluding one takes that call down with it, and the model \
then reads a conversation in which it never asked. `amend` does either.\n",
);
out
}
fn request(kernel: &Kernel) -> String {
let request = match kernel.preview_request() {
Ok(request) => request,
Err(e) => return format!("there is no request to preview: {e}\n"),
};
let projection = kernel.project();
let budget = kernel.budget();
let mut out = format!(
"{} message(s), {} tool(s), ~{} tokens{}\n\n{:>4} {:<10} {:>8} first line\n",
request.messages.len(),
request.tools.len(),
thousands(budget.used()),
budget
.limit
.map(|limit| format!(" of {}", thousands(limit)))
.unwrap_or_default(),
"#",
"role",
"bytes",
);
for (index, message) in request.messages.iter().enumerate() {
let said = message
.content
.as_ref()
.map(|c| c.to_text())
.unwrap_or_default();
out.push_str(&format!(
"{:>4} {:<10} {:>8} {}\n",
index + 1,
message.role.as_str(),
thousands(said.len()),
glimpse(&said),
));
}
if !projection.skipped.is_empty() {
out.push_str("\nleft out:\n");
for left_out in &projection.skipped {
out.push_str(&format!(" [{}] {}\n", left_out.id, left_out.reason));
}
}
if !projection.repairs.is_empty() {
out.push_str("\nrepaired, to keep the request valid:\n");
for repair in &projection.repairs {
out.push_str(&format!(" {repair}\n"));
}
}
out
}
async fn branch(
kernel: &Kernel,
question: Option<&str>,
without: &[ContextId],
output: &OutputSink,
) -> Result<ToolOutput, BoxError> {
let Some(provider) = kernel.provider() else {
return Ok(ToolOutput::error("there is no provider to ask"));
};
let mut snapshot = kernel.snapshot();
let mut left_out = Vec::new();
for item in &mut snapshot.items {
if without.contains(&item.id) {
item.state = ContextState::Excluded;
item.note = Some("left out of this fork".into());
left_out.push(item.id);
}
}
let fork = Kernel::resume(
Config {
session_name: Some(format!("{}#fork", kernel.session_name())),
context_undo_depth: 0,
max_requests_per_turn: Some(1),
..Config::default()
},
snapshot,
);
fork.set_provider(provider);
fork.set_projector(kernel.projector());
fork.push(
ContextItem::system(
"You are a copy of this session, made to think and not to act. You have no tools \
here, and nothing you ask for can be run: answer in words, from what is already in \
front of you.",
)
.pinned(),
);
if let Some(question) = question {
fork.push(ContextItem::user(question).because("put to a fork of this context"));
}
let items = fork.project().included.len();
let mut events = fork.subscribe();
let sink = output.clone();
let relay = tokio::spawn(async move {
while let Ok(event) = events.recv().await {
if let Event::ModelDelta {
delta: Delta::Text(text),
} = event
{
sink.push(text);
}
}
});
let outcome = {
let turn = fork.turn();
tokio::pin!(turn);
loop {
tokio::select! {
outcome = &mut turn => break outcome,
_ = tokio::time::sleep(HEARTBEAT) => {
if output.is_interrupted() {
fork.interrupt();
}
}
}
}
};
relay.abort();
if let Err(e) = outcome {
return Ok(ToolOutput::error(format!("the fork got no answer: {e}")));
}
let Some(response) = fork.last_response() else {
return Ok(ToolOutput::error("the fork got no answer at all"));
};
let mut out = match question {
Some(question) => format!("a copy of you, asked `{question}`, on {items} of your items"),
None => format!("what you would say if you answered now, drafted on {items} of your items"),
};
if !left_out.is_empty() {
let numbers: Vec<String> = left_out.iter().map(|id| id.to_string()).collect();
out.push_str(&format!(", without {}", numbers.join(", ")));
}
out.push_str(
". None of this is in your context and nobody has read it; it is yours to use or drop.\n",
);
if let Some(usage) = response.usage {
out.push_str(&format!(
"it cost {} in / {} out.\n",
thousands(usage.input_tokens.unwrap_or_default() as usize),
thousands(usage.output_tokens.unwrap_or_default() as usize),
));
}
if let Some(reasoning) = &response.reasoning {
out.push_str(&format!(
"\n--- its reasoning ---\n{}\n",
reasoning.to_text()
));
}
let said = response
.content
.as_ref()
.map(|content| content.to_text())
.unwrap_or_default();
match said.trim().is_empty() {
true => out.push_str(&format!(
"\n--- it said nothing ({:?}) ---\nit asked for {} instead of answering, and a fork \
has no tools; ask it something it can answer from what it already has.\n",
response.stop,
match response.calls().next() {
Some(call) => format!("`{}`", call.tool),
None => "nothing at all".to_owned(),
},
)),
false => out.push_str(&format!(
"\n--- what it said ({:?}) ---\n{said}\n",
response.stop
)),
}
Ok(ToolOutput::new(out))
}
pub struct Amend {
reach: Reach,
pinned: Pinned,
journal: Mutex<Journal>,
}
#[derive(Default)]
struct Journal {
done: Vec<Undoing>,
undone: Vec<Undoing>,
}
enum Undoing {
States(Vec<(ContextId, ContextState, Option<String>)>),
Said(ContextId, Content, Value),
}
impl Undoing {
fn apply(self, kernel: &Kernel) -> Option<Self> {
match self {
Self::States(states) => {
let mut back = Vec::new();
for (id, state, note) in states {
let Some(item) = kernel.item(id) else {
continue;
};
back.push((id, item.state, item.note.clone()));
kernel.set_state([id], state, note);
}
(!back.is_empty()).then_some(Self::States(back))
}
Self::Said(id, content, meta) => {
let item = kernel.item(id)?;
let back = Self::Said(id, item.content.clone(), item.meta.clone());
kernel.replace(id, content).ok()?;
let _ = kernel.annotate(id, meta);
Some(back)
}
}
}
fn about(&self) -> String {
match self {
Self::States(states) => format!(
"{} back to {}",
numbers(&states.iter().map(|(id, ..)| *id).collect::<Vec<_>>()),
match states.first() {
Some((_, state, _)) => state.to_string(),
None => "nothing".to_owned(),
}
),
Self::Said(id, ..) => format!("what [{id}] said"),
}
}
}
#[async_trait]
impl Tool for Amend {
fn spec(&self) -> ToolSpec {
ToolSpec::new(
"amend",
"manages your own context, so that what you carry into the next request is what you \
decided to carry. `prune` moves items: `elide` leaves a short marker in place of one, \
which is what to reach for when a tool result has served its purpose - the call it \
answers stays answered and stops costing what it holds; `exclude` takes one out \
altogether, which also takes down the call that asked for it; `archive` puts one away \
for good; `pin` protects one from being compacted away; `restore` puts one back. Name \
the items with `ids`, or with `select` for a whole class of them at once. `revise` \
rewrites what one item says, for when you wrote something down wrong. `note` writes \
something into your own context - a plan, a conclusion, a thing not to try again - \
which you can pin so that compaction cannot take it. `undo` and `redo` walk back and \
forward through the changes *you* made with this tool. Nothing here destroys \
anything: every item keeps its number and can be restored. A pinned item, a system \
instruction and the turn you are speaking in are refused - they are not yours. A \
reason is required, and it is what the person at the terminal reads. Use \
`introspect` to look first, `budget` especially.",
)
.with_schema(json!({
"type": "object",
"properties": {
"action": {
"type": "string",
"enum": ["prune", "revise", "note", "undo", "redo"],
},
"ids": {
"type": "array",
"items": { "type": "integer" },
"description": "prune: the items to move. revise: exactly one item",
},
"select": {
"type": "string",
"description": "prune: a class of items instead of `ids` - `all:tool_results`, \
`tool:shell`, `tool:shell:first`, `kind:assistant_message`, \
`state:excluded`, `file:src/x.rs`, `source:mcp`, or a number",
},
"state": {
"type": "string",
"enum": ["elide", "exclude", "archive", "pin", "restore"],
"description": "prune: where they go",
},
"content": {
"type": "string",
"description": "revise: what the item should say instead. note: what to write down",
},
"label": {
"type": "string",
"description": "note: a short name for it, so it is findable later",
},
"pin": {
"type": "boolean",
"description": "note: protect it from compaction",
},
"reason": {
"type": "string",
"description": "why, in your own words; the person at the terminal reads this",
},
"steps": {
"type": "integer",
"description": "undo, redo: how many of your own changes to walk; 1 by default",
},
},
"required": ["action", "reason"],
}))
.with_capabilities([Capability::Custom("amend".into())])
.with_output_limit(8_000)
}
async fn invoke(&self, call: &ToolCall, _output: OutputSink) -> Result<ToolOutput, BoxError> {
let kernel = self.reach.kernel()?;
let Some(reason) = call.args["reason"]
.as_str()
.filter(|r| !r.trim().is_empty())
else {
return Ok(ToolOutput::error(
"`reason` is required: it becomes the item's note, and it is what the person at \
the terminal reads when they ask why something is not in the request",
));
};
match action(&call.args)? {
"prune" => Ok(self.prune(&kernel, call, reason)),
"revise" => Ok(self.revise(&kernel, call, reason)),
"note" => Ok(self.note(&kernel, call, reason)),
"undo" => Ok(self.walk(&kernel, call, reason, true)),
"redo" => Ok(self.walk(&kernel, call, reason, false)),
other => Ok(ToolOutput::error(unknown(
other,
&["prune", "revise", "note", "undo", "redo"],
))),
}
}
}
impl Amend {
fn prune(&self, kernel: &Kernel, call: &ToolCall, reason: &str) -> ToolOutput {
let selected = call.args["select"].as_str();
let ids = match selected {
Some(input) => match input.parse::<Selector>() {
Ok(selector) => selector.matches(&kernel.items()),
Err(e) => {
return ToolOutput::error(format!(
"`{input}` is not a selector: {e}\n\n{}",
crate::ui::SELECTORS
));
}
},
None => ids(&call.args, "ids"),
};
if ids.is_empty() {
return ToolOutput::error(match selected {
Some(input) => format!(
"`{input}` is a selector, and nothing in your context matches it; \
`introspect` with `look` lists what there is"
),
None => "`prune` needs `ids`, or a `select` naming a class of them".to_owned(),
});
}
let Some(state) = state_of(call.args["state"].as_str().unwrap_or_default()) else {
return ToolOutput::error(
"`state` must be one of exclude, elide, archive, pin, restore",
);
};
let before = kernel.budget().used();
let mine = self.pinned.lock().clone();
let own = own_turn(kernel, &call.id);
let (mut allowed, mut refused) = (Vec::new(), Vec::new());
for id in ids {
match kernel.item(id) {
None => refused.push(format!("[{id}] there is no such item")),
Some(item) => match protected(&item, &mine, own) {
Some(why) => refused.push(format!("[{id}] {why}")),
None => allowed.push(id),
},
}
}
let was: Vec<_> = allowed
.iter()
.filter_map(|id| kernel.item(*id))
.map(|item| (item.id, item.state, item.note.clone()))
.collect();
let changed = kernel.set_state(allowed, state, Some(reason.to_owned()));
for id in &changed.changed {
self.note_pin(*id, state);
}
if !changed.changed.is_empty() {
let moved = was
.into_iter()
.filter(|(id, ..)| changed.changed.contains(id));
self.record(Undoing::States(moved.collect()));
}
let mut out = format!("{} item(s) are now {state}", changed.changed.len());
if !changed.changed.is_empty() {
out.push_str(&format!(": {}", numbers(&changed.changed)));
}
out.push('\n');
if !changed.unchanged.is_empty() {
out.push_str(&format!(
"{} were already: {}\n",
changed.unchanged.len(),
numbers(&changed.unchanged)
));
}
for refusal in &refused {
out.push_str(&format!("refused: {refusal}\n"));
}
out.push_str(&cost(kernel, before));
ToolOutput::new(out)
}
fn revise(&self, kernel: &Kernel, call: &ToolCall, reason: &str) -> ToolOutput {
let ids = ids(&call.args, "ids");
let [id] = ids[..] else {
return ToolOutput::error("`revise` takes exactly one id in `ids`");
};
let Some(content) = call.args["content"].as_str() else {
return ToolOutput::error("`revise` needs the `content` to put there instead");
};
let Some(item) = kernel.item(id) else {
return ToolOutput::error(format!("there is no context item {id}"));
};
if let Some(why) = protected(&item, &self.pinned.lock(), own_turn(kernel, &call.id)) {
return ToolOutput::error(format!("[{id}] {why}"));
}
let before = kernel.budget().used();
let was = item.tokens;
if let Err(e) = kernel.replace(id, Content::text(content.to_owned())) {
return ToolOutput::error(e.to_string());
}
let mut meta = match item.meta.is_object() {
true => item.meta.clone(),
false => json!({}),
};
meta["revised"] = json!({ "by": "amend", "reason": reason, "call": call.id.to_string() });
let _ = kernel.annotate(id, meta);
self.record(Undoing::Said(id, item.content.clone(), item.meta.clone()));
let now = kernel.item(id).map(|item| item.tokens).unwrap_or_default();
ToolOutput::new(format!(
"[{id}] {} now says something else: ~{} tokens instead of ~{}. What it said before is \
on the trace as `context.replaced`, and one undo brings it back.\n{}",
item.label,
thousands(now),
thousands(was),
cost(kernel, before),
))
}
fn note(&self, kernel: &Kernel, call: &ToolCall, reason: &str) -> ToolOutput {
let Some(content) = call.args["content"]
.as_str()
.filter(|c| !c.trim().is_empty())
else {
return ToolOutput::error("`note` needs the `content` to write down");
};
let label = call.args["label"].as_str().unwrap_or("note");
let pin = call.args["pin"].as_bool().unwrap_or(false);
let before = kernel.budget().used();
let id = kernel.push(
ContextItem::new(ContextKind::Reference, "agent", label, content.to_owned())
.because(reason.to_owned()),
);
if pin {
kernel.set_state([id], ContextState::Pinned, Some(reason.to_owned()));
self.note_pin(id, ContextState::Pinned);
}
self.record(Undoing::States(vec![(
id,
ContextState::Archived,
Some("a note this tool wrote, and then walked back".to_owned()),
)]));
ToolOutput::new(format!(
"[{id}] {label} is in your context now, and goes into every request from here on. {}\n{}",
match pin {
true => "It is pinned, so compaction cannot take it.",
false =>
"It is not pinned, so compaction may take it; say `pin` if it has to last.",
},
cost(kernel, before),
))
}
fn walk(&self, kernel: &Kernel, call: &ToolCall, reason: &str, back: bool) -> ToolOutput {
let steps = call.args["steps"].as_u64().unwrap_or(1).clamp(1, 64) as usize;
let before = kernel.budget().used();
let mut put_back = Vec::new();
let mut touched = Vec::new();
{
let mut journal = self.journal.lock();
for _ in 0..steps {
let taken = match back {
true => journal.done.pop(),
false => journal.undone.pop(),
};
let Some(change) = taken else {
break;
};
put_back.push(change.about());
let Some(inverse) = change.apply(kernel) else {
continue;
};
if let Undoing::States(states) = &inverse {
touched.extend(states.iter().map(|(id, ..)| *id));
}
match back {
true => journal.undone.push(inverse),
false => journal.done.push(inverse),
}
}
}
for id in touched {
if let Some(item) = kernel.item(id) {
self.note_pin(id, item.state);
}
}
let (done, undone) = {
let journal = self.journal.lock();
(journal.done.len(), journal.undone.len())
};
let direction = match back {
true => "back",
false => "forward again",
};
let mut out = match put_back.is_empty() {
true => format!(
"there was nothing of yours to walk {direction}. `undo` and `redo` only move the \
changes this tool made; the person at the terminal has an undo of their own, and \
it is not this one.\n"
),
false => format!(
"walked {} of your own change(s) {direction}, because: {reason}\n {}\n",
put_back.len(),
put_back.join("\n "),
),
};
out.push_str(&format!(
"{done} change(s) of yours can still be undone, {undone} redone.\n"
));
out.push_str(&cost(kernel, before));
ToolOutput::new(out)
}
fn record(&self, undoing: Undoing) {
let mut journal = self.journal.lock();
journal.undone.clear();
journal.done.push(undoing);
}
fn note_pin(&self, id: ContextId, state: ContextState) {
let mut mine = self.pinned.lock();
match state {
ContextState::Pinned => mine.insert(id),
_ => mine.remove(&id),
};
}
}
fn action(args: &Value) -> Result<&str, BoxError> {
args["action"]
.as_str()
.ok_or_else(|| "the `action` argument is required".into())
}
fn unknown(action: &str, known: &[&str]) -> String {
format!(
"there is no `{action}`; this tool does {}",
known.join(", ")
)
}
fn ids(args: &Value, name: &str) -> Vec<ContextId> {
args[name]
.as_array()
.map(|ids| {
ids.iter()
.filter_map(|id| id.as_u64())
.map(ContextId)
.collect()
})
.unwrap_or_default()
}
fn state_of(word: &str) -> Option<ContextState> {
Some(match word {
"exclude" | "excluded" => ContextState::Excluded,
"elide" | "elided" => ContextState::Elided,
"archive" | "archived" => ContextState::Archived,
"pin" | "pinned" => ContextState::Pinned,
"restore" | "active" => ContextState::Active,
_ => return None,
})
}
fn protected(
item: &ContextItem,
mine: &BTreeSet<ContextId>,
own_turn: Option<ContextId>,
) -> Option<String> {
if matches!(item.kind, ContextKind::System) {
return Some("a system instruction, which belongs to whoever started this session".into());
}
if item.state == ContextState::Pinned && !mine.contains(&item.id) {
return Some("pinned by the person at the terminal, and a pin is a promise".into());
}
if own_turn == Some(item.id) {
return Some("the assistant turn this very call is part of".into());
}
None
}
fn own_turn(kernel: &Kernel, call: &ToolCallId) -> Option<ContextId> {
kernel.with_context(|context| {
context
.items()
.iter()
.rev()
.find(|item| item.calls().any(|asked| &asked.id == call))
.map(|item| item.id)
})
}
fn cost(kernel: &Kernel, before: usize) -> String {
let budget = kernel.budget();
format!(
"the next request is now ~{} tokens{}, from ~{}.\n",
thousands(budget.used()),
budget
.limit
.map(|limit| format!(" of {}", thousands(limit)))
.unwrap_or_default(),
thousands(before),
)
}
fn numbers(ids: &[ContextId]) -> String {
ids.iter()
.map(|id| id.to_string())
.collect::<Vec<_>>()
.join(", ")
}
fn glimpse(text: &str) -> String {
let first = text
.lines()
.find(|line| !line.trim().is_empty())
.unwrap_or_default();
match first.chars().count() > GLIMPSE {
true => format!("{}…", first.chars().take(GLIMPSE - 1).collect::<String>()),
false => first.to_owned(),
}
}