Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(workstream): add a v2-engine Kiro CLI managed-workstream adapter
Samir Hanna Verza4429adc34c6c
diff --git a/README.md b/README.mdindex 10ffcf85..8ec8d9d2 100644--- a/README.md+++ b/README.md@@ -74,13 +74,15 @@ priors are at the [bottom](#influences-and-prior-art).and full-ledger search. Delivered packets are origin-marked; Claude transcriptimport rejects a packet that Claude persisted and read back through a tool.`ai-memory run` with no harness continues the newest usable Claude Code,- Codex, OpenCode, Pi, Crush, or Kimi Code session for this checkout. On first+ Codex, OpenCode, Pi, Crush, Kimi Code, or Kiro CLI session for this checkout.+ On firstexplicit use, an interactive launcher can adopt a previous session from thesame checkout; later switches cannot select unrelated native history. Nativearguments pass through unchanged except the wrapper-owned `--yolo` and`--fresh`; directcommands are unaffected. `kimi-code` and `kimi-cli` are accepted aliases for- the installed `kimi` command.+ the installed `kimi` command, and `kiro-cli` for the installed `kiro-cli`+ command (`ai-memory run kiro`, default v2 engine only).- **Per-repository capture exclusions.** A nearest-marker `[capture]``ignore_paths` policy drops matching recognized file-tool events before theyreach the local spool or server. See [the capture policy reference](docs/marker-file.md#capture-exclusions).diff --git a/crates/ai-memory-cli/src/commands/run.rs b/crates/ai-memory-cli/src/commands/run.rsindex 11b18481..203cf3ab 100644--- a/crates/ai-memory-cli/src/commands/run.rs+++ b/crates/ai-memory-cli/src/commands/run.rs@@ -36,13 +36,14 @@ const PREPARE_BUSY_RETRY_INTERVAL: Duration = Duration::from_millis(250);const IMPORT_BATCH_EVENTS: usize = 400;const IMPORT_BATCH_BYTES: usize = 1024 * 1024;const ADOPTION_CANDIDATE_LIMIT: usize = 8;-const AUTO_HARNESSES: [ManagedHarness; 6] = [+const AUTO_HARNESSES: [ManagedHarness; 7] = [ManagedHarness::Claude,ManagedHarness::Codex,ManagedHarness::OpenCode,ManagedHarness::Pi,ManagedHarness::Crush,ManagedHarness::Kimi,+ ManagedHarness::Kiro,];#[derive(Debug, Clone)]@@ -293,6 +294,16 @@ pub(super) async fn run_from(config: &Config, args: RunArgs, cwd: &Path) -> Resu}}if args.yolo || trailing_yolo {+ // Kiro's official dangerous mode exists on the v2 engine only+ // (`--trust-all-tools`); the v3 engine replaced it with+ // permissions.yaml and documents no CLI equivalent, so the wrapper+ // maps nothing there and says so instead of failing silently.+ if harness == ManagedHarness::Kiro && kiro_selects_non_default_engine(&plan.args) {+ eprintln!(+ "ai-memory: --yolo maps to no verified flag on the selected Kiro engine \+ (v3 replaced --trust-all-tools with permissions.yaml); launching without it"+ );+ }apply_yolo(harness, &mut plan.args);}if plan.mode == LaunchMode::Session@@ -631,7 +642,7 @@ fn filter_usable_auto_sessions(fn no_auto_session_error() -> anyhow::Error {anyhow!(- "no Claude Code, Codex, OpenCode, Pi, Crush, or Kimi Code session was found for this directory; start one explicitly with `ai-memory run claude`, `ai-memory run codex`, `ai-memory run opencode`, `ai-memory run pi`, `ai-memory run crush`, or `ai-memory run kimi`"+ "no Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, or Kiro CLI session was found for this directory; start one explicitly with `ai-memory run claude`, `ai-memory run codex`, `ai-memory run opencode`, `ai-memory run pi`, `ai-memory run crush`, `ai-memory run kimi`, or `ai-memory run kiro`")}@@ -1648,6 +1659,32 @@ mod tests {);}+ #[test]+ fn kiro_cli_alias_selects_the_kiro_adapter() {+ for name in ["kiro", "kiro-cli"] {+ let cli = Cli::try_parse_from([+ OsStr::new("ai-memory"),+ OsStr::new("run"),+ OsStr::new(name),+ OsStr::new("--model"),+ OsStr::new("sonnet"),+ ])+ .unwrap();+ let CliCommand::Run(args) = cli.command else {+ panic!("expected run command");+ };+ assert!(+ matches!(args.harness, Some(crate::cli::RunHarnessChoice::Kiro)),+ "{name}"+ );+ assert_eq!(+ args.native_args,+ ["--model", "sonnet"].map(OsString::from).to_vec()+ );+ assert_eq!(managed_harness(args.harness.unwrap()), ManagedHarness::Kiro);+ }+ }+#[test]fn bare_run_and_wrapper_yolo_parse_without_a_harness() {let cli = Cli::try_parse_from(["ai-memory", "run", "--yolo"]).unwrap();diff --git a/crates/ai-memory-hooks/src/workstream.rs b/crates/ai-memory-hooks/src/workstream.rsindex 03c2b763..290ce0e8 100644--- a/crates/ai-memory-hooks/src/workstream.rs+++ b/crates/ai-memory-hooks/src/workstream.rs@@ -144,13 +144,14 @@ async fn prepare_run("managed run requires a supported command-line harness",);}- const AUTO_AGENTS: [AgentKind; 6] = [+ const AUTO_AGENTS: [AgentKind; 7] = [AgentKind::ClaudeCode,AgentKind::Codex,AgentKind::OpenCode,AgentKind::Pi,AgentKind::Crush,AgentKind::KimiCode,+ AgentKind::KiroCli,];if request.automatic_harness&& (!AUTO_AGENTS.contains(&request.agent)diff --git a/crates/ai-memory-workstream/src/harness.rs b/crates/ai-memory-workstream/src/harness.rsindex e5ae6364..aeb75d1e 100644--- a/crates/ai-memory-workstream/src/harness.rs+++ b/crates/ai-memory-workstream/src/harness.rs@@ -97,6 +97,28 @@ impl ManagedHarness {}}+/// Whether a Kiro CLI invocation targets an agent engine other than the+/// default v2 engine — `--v3`, `--mode` (a v3-only option), or an+/// `--agent-engine` value that is not `v2` (the `chat` subcommand's+/// engine selector, verified on kiro-cli 2.16.0).+///+/// Kiro v3 sessions live in a separate id space and cannot be resumed by+/// the v2 engine (nor vice versa), and the v3 persisted-session format is+/// not publicly documented, so managed continuity covers the v2 engine+/// only. Any non-v2 engine selection makes the whole invocation pass+/// through — no session injection, no adoption, no import — which keeps+/// incompatible v2/v3 sessions from being cross-resumed by construction.+#[must_use]+pub fn kiro_selects_non_default_engine(args: &[OsString]) -> bool {+ if has_flag(args, &["--v3", "--mode"]) {+ return true;+ }+ if !has_flag(args, &["--agent-engine"]) {+ return false;+ }+ flag_value(args, &["--agent-engine"]).as_deref() != Some("v2")+}+/// Whether the planned native invocation participates in session continuity.#[derive(Debug, Clone, Copy, PartialEq, Eq)]pub enum LaunchMode {@@ -315,11 +337,42 @@ fn noninteractive_invocation(harness: ManagedHarness, args: &[OsString]) -> bool}fn launch_mode(harness: ManagedHarness, args: &[OsString]) -> LaunchMode {- if has_flag(args, &["--help", "-h", "--version", "-v"])+ // Kiro's `-v` is verbose (its version short flag is `-V`), so the+ // generic version-flag check must not send `kiro-cli -v` through+ // unmanaged.+ let version_flags: &[&str] = if harness == ManagedHarness::Kiro {+ &["--help", "-h", "--version", "-V", "--help-all"]+ } else {+ &["--help", "-h", "--version", "-v"]+ };+ if has_flag(args, version_flags)|| has_flag(args, &["--no-session", "--no-session-persistence"]){return LaunchMode::Passthrough;}+ if harness == ManagedHarness::Kiro {+ // Managed continuity is verified for the default v2 engine only;+ // any other engine selection passes straight through (see+ // `kiro_selects_non_default_engine`). Headless `--no-interactive`+ // runs persist to the v1 SQLite store rather than the v2 session+ // files this adapter reads, and the one-shot list/delete flags+ // never open a session, so none of them is session-bearing.+ if kiro_selects_non_default_engine(args)+ || has_flag(+ args,+ &[+ "--no-interactive",+ "--list-sessions",+ "-l",+ "--list-models",+ "--delete-session",+ "-d",+ ],+ )+ {+ return LaunchMode::Passthrough;+ }+ }if harness == ManagedHarness::Codex&& first_arg_is(args, "exec")&& argsdiff --git a/crates/ai-memory-workstream/src/transcript.rs b/crates/ai-memory-workstream/src/transcript.rsindex cda7f94b..bb33ecc7 100644--- a/crates/ai-memory-workstream/src/transcript.rs+++ b/crates/ai-memory-workstream/src/transcript.rs@@ -300,7 +300,9 @@ fn export_jsonl(// on fork/compaction/resume, Grok on rewind) — a byte-offset id// would silently change meaning. Hashing the raw line keeps// record ids (and therefore server-side event dedup) stable- // across rewrites.+ // across rewrites. Kiro records reuse one message_id across an+ // exchange's Prompt/AssistantMessage/ToolResults records, so+ // the line hash is its unique record id as well.let raw = line.strip_suffix(b"\n").unwrap_or(&line);format!("{:x}", Sha256::digest(raw))} else {@@ -367,6 +369,17 @@ fn export_jsonl(})}+/// Journals the harness may rewrite in place (fork/compaction/resume),+/// where a byte-offset cursor would silently change meaning: the adapter+/// validates a prefix hash before trusting the offset and derives record+/// ids from the raw line bytes. Kimi is a confirmed rewriter; Kiro's+/// event stream is not verified append-only, so it gets the same+/// tolerance defensively (a rewrite resets the cursor and the stable+/// line-hash record ids dedupe the replay server-side).+const fn rewrite_tolerant_journal(harness: ManagedHarness) -> bool {+ matches!(harness, ManagedHarness::Kimi | ManagedHarness::Kiro)+}+fn hash_file_prefix(file: &mut File, len: u64) -> Result<Option<Sha256>> {file.seek(SeekFrom::Start(0))?;let mut hasher = Sha256::new();@@ -944,6 +957,185 @@ fn kimi_timestamp(value: &Value) -> Option<String> {.map(|timestamp| timestamp.to_string())}+/// Import one Kiro v2-engine session event: a versioned envelope+/// `{"version":"v1","kind":…,"data":{"message_id":…,"content":[…],"meta":…}}`+/// whose `content` parts carry their own `kind`/`data`. Visible kinds:+/// `Prompt` (user), `AssistantMessage` (assistant text + `toolUse` parts),+/// `ToolResults` (`toolResult` parts). Unknown record kinds within the+/// `v1` envelope are ignored so newer Kiro versions stay+/// forward-compatible; a non-`v1` envelope version is annotated instead —+/// that axis signals a schema break, not an additive record type.+fn parse_kiro(+ value: &Value,+ session: &str,+ record_id: &str,+ events: &mut Vec<NewWorkstreamEvent>,+ losses: &mut Vec<String>,+) {+ match value.get("version").and_then(Value::as_str) {+ Some("v1") => {}+ Some(other) => {+ losses.push(format!(+ "Kiro records with unsupported envelope version {other} were skipped"+ ));+ return;+ }+ None => {+ losses.push("Kiro records without an envelope version were skipped".into());+ return;+ }+ }+ let data = value.get("data").unwrap_or(&Value::Null);+ let occurred_at = kiro_timestamp(data);+ let parts = data+ .get("content")+ .and_then(Value::as_array)+ .map_or(&[][..], Vec::as_slice);+ match value+ .get("kind")+ .and_then(Value::as_str)+ .unwrap_or_default()+ {+ "Prompt" => {+ for (index, part) in parts.iter().enumerate() {+ match part.get("kind").and_then(Value::as_str).unwrap_or_default() {+ "text" => {+ if let Some(text) = part.get("data").and_then(Value::as_str) {+ push_event(+ events,+ AgentKind::KiroCli,+ session,+ record_id,+ index,+ WorkstreamEventKind::Message,+ Some("user"),+ text,+ occurred_at.clone(),+ json!({}),+ );+ }+ }+ _ => {+ losses+ .push("Kiro non-text content parts were intentionally excluded".into());+ }+ }+ }+ }+ "AssistantMessage" => {+ for (index, part) in parts.iter().enumerate() {+ match part.get("kind").and_then(Value::as_str).unwrap_or_default() {+ "text" => {+ if let Some(text) = part.get("data").and_then(Value::as_str) {+ push_event(+ events,+ AgentKind::KiroCli,+ session,+ record_id,+ index,+ WorkstreamEventKind::Message,+ Some("assistant"),+ text,+ occurred_at.clone(),+ json!({}),+ );+ }+ }+ "toolUse" => {+ let tool = part.get("data").unwrap_or(&Value::Null);+ let name = first_string(tool, &["name", "toolName", "tool_name"])+ .unwrap_or("tool");+ let arguments = tool+ .get("input")+ .or_else(|| tool.get("args"))+ .or_else(|| tool.get("arguments"))+ .map(compact_json)+ .unwrap_or_else(|| compact_json(tool));+ push_event(+ events,+ AgentKind::KiroCli,+ session,+ record_id,+ index,+ WorkstreamEventKind::ToolCall,+ Some("assistant"),+ &format!("{name}: {arguments}"),+ occurred_at.clone(),+ json!({+ "tool": name,+ "tool_call_id": first_string(tool, &["tool_use_id", "toolUseId", "id"])+ }),+ );+ }+ _ => {+ losses+ .push("Kiro non-text content parts were intentionally excluded".into());+ }+ }+ }+ }+ "ToolResults" => {+ for (index, part) in parts.iter().enumerate() {+ if part.get("kind").and_then(Value::as_str) != Some("toolResult") {+ continue;+ }+ let result = part.get("data").unwrap_or(&Value::Null);+ let body = kiro_result_text(result)+ .filter(|text| !text.trim().is_empty())+ .unwrap_or_else(|| compact_json(result));+ push_event(+ events,+ AgentKind::KiroCli,+ session,+ record_id,+ index,+ WorkstreamEventKind::ToolResult,+ Some("tool"),+ &body,+ occurred_at.clone(),+ json!({+ "tool_call_id": first_string(result, &["tool_use_id", "toolUseId", "id"]),+ "is_error": result+ .get("is_error")+ .or_else(|| result.get("isError"))+ .and_then(Value::as_bool)+ }),+ );+ }+ }+ _ => {}+ }+}++/// Kiro event timestamps ride `data.meta.timestamp` as a unix epoch in+/// milliseconds.+fn kiro_timestamp(data: &Value) -> Option<String> {+ let millis = data.get("meta")?.get("timestamp").and_then(Value::as_i64)?;+ jiff::Timestamp::from_millisecond(millis)+ .ok()+ .map(|timestamp| timestamp.to_string())+}++/// Text of a Kiro tool result: its `content` is an array of the same+/// `{kind, data}` parts the message records use (text parts join), with+/// plain-string `content`/`output`/`text` fields tolerated as fallbacks.+fn kiro_result_text(result: &Value) -> Option<String> {+ if let Some(parts) = result.get("content").and_then(Value::as_array) {+ let texts: Vec<&str> = parts+ .iter()+ .filter(|part| part.get("kind").and_then(Value::as_str) == Some("text"))+ .filter_map(|part| part.get("data").and_then(Value::as_str))+ .collect();+ if !texts.is_empty() {+ return Some(texts.join("\n"));+ }+ }+ ["content", "output", "text"]+ .iter()+ .find_map(|key| result.get(*key).and_then(Value::as_str))+ .map(str::to_owned)+}+/// Subagent journals (`agents/<id != main>/wire.jsonl`) are not imported in/// v1; annotate the gap once so the omission is visible in the ledger.fn annotate_kimi_subagents(path: &Path, losses: &mut Vec<String>) {@@ -1602,6 +1794,13 @@ fn locate_session_file(}}}+ if harness == ManagedHarness::Kiro {+ // The store is flat: `<root>/<session-id>.jsonl`.+ let exact = root.join(format!("{id}.jsonl"));+ if exact.is_file() {+ return Ok(Some(exact));+ }+ }let mut files = collect_files(&root, |path| transcript_file(harness, path))?;files.sort_by_key(|path| temporary_transcript(path));for path in &files {diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.mdindex 5a824a36..7f97e809 100644--- a/docs/managed-workstreams.md+++ b/docs/managed-workstreams.md@@ -118,8 +118,8 @@ directory, including automatic harness selection. `continue` therefore accepts## Automatic harness selectionWith no harness name, `ai-memory run` inspects checkout-local sessions for-Claude Code, Codex, OpenCode, Pi, Crush, and Kimi Code. For an empty workstream-it resumes+Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, and Kiro CLI. For an empty+workstream it resumesthe newest session automatically. For an established workstream, server statetakes precedence: ai-memory resumes the most recently linked harness that stillhas a usable local session. It never chooses a newer but obsolete session from@@ -225,6 +225,7 @@ is labelled completed evidence and must never be replayed as a pending call.| Pi | generated `--session-id` | `--session <id>` | `~/.pi/agent/sessions/**/*.jsonl` || Crush | native default creation | `--session <id>` | `<project>/.crush/crush.db` opened read-only || Kimi Code | native default creation | `--session <id>` | `$KIMI_CODE_HOME/sessions/*/*/agents/main/wire.jsonl` |+| Kiro CLI | native default creation | `--resume-id <id>` | `$KIRO_HOME/sessions/cli/<uuid>.jsonl` (+ sibling `<uuid>.json` metadata) || OMP | native default creation | `--resume=<id>` | `~/.omp/agent/sessions/**/*.jsonl` || Grok Build CLI | generated `--session-id` | `--resume <id>` | `$GROK_HOME/sessions/*/*/chat_history.jsonl` || Antigravity CLI | native default creation | `--conversation <id>` | `~/.gemini/antigravity-cli/conversations/<id>.db` metadata plus lifecycle-hook capture |@@ -276,6 +277,7 @@ ai-memory install-hooks --agent opencode --applyai-memory install-hooks --agent pi --applyai-memory install-hooks --agent omp --applyai-memory install-hooks --agent kimi-code --apply+ai-memory install-hooks --agent kiro-cli --apply```Kimi Code hooks installed as native `ai-memory hook` commands automaticallydiff --git a/scripts/managed-workstream-acceptance.sh b/scripts/managed-workstream-acceptance.shindex b7bc4651..39768363 100755--- a/scripts/managed-workstream-acceptance.sh+++ b/scripts/managed-workstream-acceptance.sh@@ -217,6 +217,37 @@ case "${AI_MEMORY_ACCEPTANCE_FAKE_MODE:-argv}" inpacket=$(jq -r '.options.global_context_paths[-1]' "$CRUSH_GLOBAL_CONFIG/crush.json")cp "$packet" "$AI_MEMORY_ACCEPTANCE_CRUSH_PACKET_LOG";;+ kiro)+ printf '%s\n' "$@" >"$AI_MEMORY_ACCEPTANCE_ARGV_LOG"+ # Honor `--resume-id <id>` (resume); a fresh launch mints its own id+ # because Kiro CLI session ids are server-assigned UUIDs.+ session_id=""+ previous_arg=""+ for arg in "$@"; do+ if [ "$previous_arg" = --resume-id ]; then+ session_id=$arg+ fi+ previous_arg=$arg+ done+ if [ -z "$session_id" ]; then+ session_id=$(cat /proc/sys/kernel/random/uuid)+ fi+ # Real layout: flat store, one `<uuid>.json` metadata + `<uuid>.jsonl`+ # event-stream pair per session; discovery must read the metadata cwd.+ store="${KIRO_HOME:?kiro fake mode requires KIRO_HOME}/sessions/cli"+ mkdir -p "$store"+ stream="$store/$session_id.jsonl"+ if [ ! -f "$store/$session_id.json" ]; then+ printf '{"session_id":"%s","cwd":"%s","created_at":"2026-08-01T10:00:00Z","updated_at":"2026-08-01T10:00:00Z","title":"acceptance","session_state":{"version":"v1","conversation_metadata":{}}}\n' \+ "$session_id" "$PWD" >"$store/$session_id.json"+ : >"$stream"+ fi+ sentinel=${AI_MEMORY_ACCEPTANCE_SENTINEL:-AMWS-FAKE-KIRO}+ printf '{"version":"v1","kind":"Prompt","data":{"message_id":"m-%s-u","content":[{"kind":"text","data":"%s"}],"meta":{"timestamp":%s}}}\n' \+ "$(date +%s)" "$sentinel" "$(date +%s)000" >>"$stream"+ printf '{"version":"v1","kind":"AssistantMessage","data":{"message_id":"m-%s-a","content":[{"kind":"text","data":"%s reply"}],"meta":{"timestamp":%s}}}\n' \+ "$(date +%s)" "$sentinel" "$(date +%s)000" >>"$stream"+ ;;kimi)printf '%s\n' "$@" >"$AI_MEMORY_ACCEPTANCE_ARGV_LOG"# Honor `--session <id>` (resume); a fresh launch mints its own id