use std::borrow::Cow;
use std::future::Future;
use std::pin::Pin;
use std::process::Command;
use std::sync::Arc;
use incurs::command::{CommandBuilder, CommandDef, McpCommandOptions, TypedContext, TypedResult};
use incurs::errors::ValidationError;
use incurs::middleware::MiddlewareFn;
use incurs::output::CtaBlock;
use incurs::schema::{FieldMeta, FieldType, IncurSchema};
use schemars::{JsonSchema, Schema, SchemaGenerator};
use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use sha2::{Digest, Sha256};
use crate::hook::HookPhase;
use crate::model::{
InvocationRecord, InvocationScopeKind, InvocationSource, InvocationStatus, InvocationSurface,
now_ms,
};
use crate::process::controller;
use crate::store::Store;
#[derive(Clone)]
struct ActiveInvocation {
id: String,
command_path: String,
store: Arc<Store>,
hook_depth: u32,
}
tokio::task_local! {
static ACTIVE_INVOCATION: ActiveInvocation;
}
struct PurposeOptions<Options> {
purpose: String,
options: Options,
}
struct MutationOptions<Options> {
purpose: String,
idempotency_key: String,
options: Options,
}
impl<Options: IncurSchema> IncurSchema for PurposeOptions<Options> {
fn fields() -> Vec<FieldMeta> {
let mut fields = Options::fields();
if let Some(field) = fields.iter_mut().find(|field| field.name == "purpose") {
field.required = true;
field.description = Some(
"Brief user-facing summary of what this apoc call is doing. Never include secrets.",
);
} else {
fields.push(purpose_field());
}
fields
}
fn from_raw(raw: &std::collections::BTreeMap<String, Value>) -> Result<Self, ValidationError> {
let purpose = raw
.get("purpose")
.and_then(Value::as_str)
.ok_or_else(|| purpose_error("Purpose is required"))?;
let purpose = purpose.trim();
if purpose.is_empty() {
return Err(purpose_error("Purpose cannot be empty"));
}
if purpose.chars().any(char::is_control) {
return Err(purpose_error(
"Purpose must be one line without control characters",
));
}
let mut normalized = raw.clone();
normalized.insert("purpose".to_string(), Value::String(purpose.to_string()));
Ok(Self {
purpose: purpose.to_string(),
options: Options::from_raw(&normalized)?,
})
}
}
impl<Options: IncurSchema> IncurSchema for MutationOptions<Options> {
fn fields() -> Vec<FieldMeta> {
let mut fields = PurposeOptions::<Options>::fields();
if let Some(field) = fields
.iter_mut()
.find(|field| field.name == "idempotency_key")
{
field.required = true;
field.description = Some(
"Stable caller key that returns the original mutation receipt without applying the mutation twice.",
);
} else {
fields.push(idempotency_key_field());
}
fields
}
fn from_raw(raw: &std::collections::BTreeMap<String, Value>) -> Result<Self, ValidationError> {
let PurposeOptions { purpose, .. } = PurposeOptions::<Options>::from_raw(raw)?;
let idempotency_key = raw
.get("idempotency_key")
.and_then(Value::as_str)
.ok_or_else(|| purpose_error("Idempotency key is required"))?;
let idempotency_key = idempotency_key.trim();
if idempotency_key.is_empty() {
return Err(purpose_error("Idempotency key cannot be empty"));
}
if idempotency_key.chars().any(char::is_control) {
return Err(purpose_error(
"Idempotency key must be one line without control characters",
));
}
let mut normalized = raw.clone();
normalized.insert("purpose".to_string(), Value::String(purpose.clone()));
normalized.insert(
"idempotency_key".to_string(),
Value::String(idempotency_key.to_string()),
);
Ok(Self {
purpose,
idempotency_key: idempotency_key.to_string(),
options: Options::from_raw(&normalized)?,
})
}
}
fn purpose_field() -> FieldMeta {
FieldMeta {
name: "purpose",
cli_name: "purpose".to_string(),
description: Some(
"Brief user-facing summary of what this apoc call is doing. Never include secrets.",
),
field_type: FieldType::String,
required: true,
default: None,
alias: None,
deprecated: false,
env_name: None,
}
}
fn idempotency_key_field() -> FieldMeta {
FieldMeta {
name: "idempotency_key",
cli_name: "idempotency-key".to_string(),
description: Some(
"Stable caller key that returns the original mutation receipt without applying the mutation twice.",
),
field_type: FieldType::String,
required: true,
default: None,
alias: None,
deprecated: false,
env_name: None,
}
}
fn purpose_error(message: &str) -> ValidationError {
ValidationError {
message: message.to_string(),
field_errors: Vec::new(),
cause: None,
}
}
pub(crate) fn invocation_purpose(globals: &Value) -> &str {
globals
.get("purpose")
.and_then(Value::as_str)
.expect("tracked apoc commands always carry a validated purpose")
}
pub(crate) struct InvocationScope {
pub(crate) cwd: Option<String>,
pub(crate) kind: InvocationScopeKind,
pub(crate) key: Option<String>,
}
pub(crate) fn active_invocation_id() -> Option<String> {
ACTIVE_INVOCATION.try_with(|active| active.id.clone()).ok()
}
pub(crate) fn active_store() -> Option<Arc<Store>> {
ACTIVE_INVOCATION
.try_with(|active| Arc::clone(&active.store))
.ok()
}
pub(crate) fn invocation_scope(cwd: Option<&str>) -> InvocationScope {
let Some(cwd) = cwd else {
return InvocationScope {
cwd: None,
kind: InvocationScopeKind::Unknown,
key: None,
};
};
let cwd = std::fs::canonicalize(cwd)
.ok()
.unwrap_or_else(|| std::path::PathBuf::from(cwd));
let cwd = cwd.to_string_lossy().into_owned();
let worktree = Command::new("git")
.args(["rev-parse", "--show-toplevel"])
.current_dir(&cwd)
.output()
.ok()
.filter(|output| output.status.success())
.and_then(|output| String::from_utf8(output.stdout).ok())
.map(|value| value.trim().to_string())
.filter(|value| !value.is_empty())
.and_then(|value| {
std::fs::canonicalize(value)
.ok()
.map(|path| path.to_string_lossy().into_owned())
});
match worktree {
Some(worktree) => InvocationScope {
cwd: Some(cwd),
kind: InvocationScopeKind::GitWorktree,
key: Some(worktree),
},
None => InvocationScope {
cwd: Some(cwd.clone()),
kind: InvocationScopeKind::Cwd,
key: Some(cwd),
},
}
}
pub(crate) fn invocation_middleware(store: Option<Arc<Store>>) -> MiddlewareFn {
Arc::new(move |context, next| {
let configured_store = store.clone();
Box::pin(async move {
let store = configured_store.or_else(|| match Store::open_default() {
Ok(store) => Some(Arc::new(store)),
Err(error) => {
crate::error_telemetry::record(
"history",
"invocation.start",
"HISTORY_STORE_OPEN_FAILED",
None,
None,
&error,
);
None
}
});
let Some(store) = store else {
next().await;
return;
};
let controller = controller(context.agent);
let parent_id = active_invocation_id();
let scope = invocation_scope(controller.cwd.as_deref());
let surface = match context
.request
.as_ref()
.map(|request| request.method.as_str())
{
Some("code") => InvocationSurface::Code,
Some(_) => InvocationSurface::Mcp,
None => InvocationSurface::Cli,
};
let recording = (!context.command.starts_with("recording"))
.then(|| {
store
.active_recording(scope.kind, scope.key.as_deref())
.unwrap_or_default()
})
.flatten();
let recording_take = recording
.as_ref()
.and_then(|recording| recording.takes.last())
.map(|take| take.index);
let at = now_ms();
let invocation = InvocationRecord {
id: controller.invocation_id,
parent_id,
execution_id: controller.execution_id,
source: InvocationSource::Native,
source_id: None,
source_order: None,
source_path: None,
accepted_sequence: 0,
surface,
actor: Some(controller.actor),
agent: controller.agent,
command_path: context.command.clone(),
purpose: None,
normalized_input: serde_json::json!({}),
search_text: context.command.clone(),
pattern_signature: String::new(),
variable_paths: Vec::new(),
cwd: scope.cwd,
scope_kind: scope.kind,
scope_key: scope.key,
recording_id: recording.map(|recording| recording.id),
recording_take,
started_at: at,
completed_at: None,
updated_at: at,
status: InvocationStatus::Running,
exit_code: None,
error_code: None,
error: None,
};
if let Err(error) = store.start_invocation(&invocation) {
crate::error_telemetry::record_at(
store.path().parent().unwrap_or(std::path::Path::new(".")),
"history",
"invocation.start",
"HISTORY_WRITE_FAILED",
Some(&invocation.id),
invocation.execution_id.as_deref(),
&error,
);
tracing::warn!(error = %error, "could not record apoc invocation");
next().await;
return;
}
let active = ActiveInvocation {
id: invocation.id.clone(),
command_path: invocation.command_path,
store: Arc::clone(&store),
hook_depth: controller.hook_depth,
};
ACTIVE_INVOCATION.scope(active, next()).await;
if store
.get_invocation(&invocation.id)
.ok()
.flatten()
.is_some_and(|record| record.status == InvocationStatus::Running)
&& let Ok(Some(invocation)) = store.finish_invocation(
&invocation.id,
InvocationStatus::Incomplete,
Some(now_ms()),
None,
None,
None,
)
{
let _ = store.enqueue_hook_deliveries(
&invocation,
HookPhase::Failure,
controller.hook_depth,
);
}
})
})
}
#[derive(Debug, Clone, Serialize, Deserialize)]
struct MutationReplay {
fingerprint: String,
result: MutationReplayResult,
}
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(tag = "state", rename_all = "snake_case")]
enum MutationReplayResult {
Intent,
Ok {
data: Value,
cta: Option<CtaBlock>,
exit_code: Option<i32>,
},
Error {
code: String,
message: String,
retryable: bool,
exit_code: Option<i32>,
cta: Option<CtaBlock>,
},
}
enum MutationOutput<Output> {
Fresh(Output),
Replayed(Value),
}
impl<Output: Serialize> Serialize for MutationOutput<Output> {
fn serialize<Serializer>(
&self,
serializer: Serializer,
) -> Result<Serializer::Ok, Serializer::Error>
where
Serializer: serde::Serializer,
{
match self {
Self::Fresh(output) => output.serialize(serializer),
Self::Replayed(output) => output.serialize(serializer),
}
}
}
impl<Output: JsonSchema> JsonSchema for MutationOutput<Output> {
fn inline_schema() -> bool {
Output::inline_schema()
}
fn schema_name() -> Cow<'static, str> {
Output::schema_name()
}
fn schema_id() -> Cow<'static, str> {
Output::schema_id()
}
fn json_schema(generator: &mut SchemaGenerator) -> Schema {
Output::json_schema(generator)
}
}
pub(crate) struct TrackedCommandBuilder {
read_only: CommandBuilder,
mutating: CommandBuilder,
mutation: bool,
}
impl TrackedCommandBuilder {
pub(crate) fn description(mut self, description: impl Into<String>) -> Self {
let description = description.into();
self.read_only = self.read_only.description(description.clone());
self.mutating = self.mutating.description(description);
self
}
pub(crate) fn command_aliases(mut self, aliases: Vec<String>) -> Self {
self.read_only = self.read_only.command_aliases(aliases.clone());
self.mutating = self.mutating.command_aliases(aliases);
self
}
pub(crate) fn mcp(mut self, options: McpCommandOptions) -> Self {
let annotated_mutation = options.annotations.as_ref().is_some_and(|annotations| {
annotations.read_only_hint == Some(false) || annotations.destructive_hint == Some(true)
});
self.mutation |= annotated_mutation || options.destructive;
self.read_only = self.read_only.mcp(options.clone());
self.mutating = self.mutating.mcp(options);
self
}
pub(crate) fn destructive(mut self, destructive: bool) -> Self {
self.mutation |= destructive;
self.read_only = self.read_only.destructive(destructive);
self.mutating = self.mutating.destructive(destructive);
self
}
pub(crate) fn done(self) -> CommandDef {
if self.mutation {
self.mutating.done()
} else {
self.read_only.done()
}
}
}
pub(crate) fn tracked_typed<Args, Options, Env, Output, Handler, HandlerFuture>(
name: impl Into<String>,
handler: Handler,
) -> TrackedCommandBuilder
where
Args: incurs::schema::IncurSchema + Serialize + Send + Sync + 'static,
Options: incurs::schema::IncurSchema + Serialize + Send + Sync + 'static,
Env: incurs::schema::IncurSchema + Serialize + Send + Sync + 'static,
Output: JsonSchema + Serialize + Send + Sync + 'static,
Handler: Fn(TypedContext<Args, Options, Env>) -> HandlerFuture + Send + Sync + 'static,
HandlerFuture: Future<Output = TypedResult<Output>> + Send + 'static,
{
let name = name.into();
let handler = Arc::new(handler);
let native_idempotency = Options::fields()
.iter()
.any(|field| field.name == "idempotency_key");
let read_handler = Arc::clone(&handler);
let read_only = CommandDef::typed::<Args, PurposeOptions<Options>, Env, Output, _, _>(
name.clone(),
move |context| {
let handler = Arc::clone(&read_handler);
let TypedContext {
agent,
args,
display_name,
env,
mut globals,
options,
request,
format,
format_explicit,
name,
vars,
version,
} = context;
let PurposeOptions { purpose, options } = options;
let mut serialized_options = serde_json::to_value(&options).unwrap_or(Value::Null);
if let Some(object) = serialized_options.as_object_mut() {
object.remove("purpose");
}
let input = redact_history_input(serde_json::json!({
"purpose": &purpose,
"args": &args,
"options": serialized_options,
}));
if !globals.is_object() {
globals = json!({});
}
globals
.as_object_mut()
.expect("globals was normalized to an object")
.insert("purpose".to_string(), Value::String(purpose.clone()));
let context = TypedContext {
agent,
args,
display_name,
env,
globals,
options,
request,
format,
format_explicit,
name,
vars,
version,
};
Box::pin(async move {
let active = ACTIVE_INVOCATION.try_with(Clone::clone).ok();
if let Some(active) = &active {
let search_text = format!(
"{} {}",
active.command_path,
serde_json::to_string(&input).unwrap_or_default()
);
update_input(active, Some(purpose), input, search_text);
}
let result = handler(context).await;
if let Some(active) = active {
finish(&active, &result);
}
result
}) as Pin<Box<dyn Future<Output = TypedResult<Output>> + Send>>
},
);
let mutating = CommandDef::typed::<
Args,
MutationOptions<Options>,
Env,
MutationOutput<Output>,
_,
_,
>(name, move |context| {
let handler = Arc::clone(&handler);
let TypedContext {
agent,
args,
display_name,
env,
mut globals,
options,
request,
format,
format_explicit,
name,
vars,
version,
} = context;
let MutationOptions {
purpose,
idempotency_key,
options,
} = options;
let mut serialized_options = serde_json::to_value(&options).unwrap_or(Value::Null);
if let Some(object) = serialized_options.as_object_mut() {
object.remove("purpose");
object.remove("idempotency_key");
}
let input = redact_history_input(serde_json::json!({
"purpose": &purpose,
"idempotency_key": &idempotency_key,
"args": &args,
"options": &serialized_options,
}));
let fingerprint_input = serde_json::json!({
"args": &args,
"options": &serialized_options,
"env": &env,
});
globals = globals_with_purpose(globals, &purpose);
globals
.as_object_mut()
.expect("globals was normalized to an object")
.insert(
"idempotency_key".to_string(),
Value::String(idempotency_key.clone()),
);
let context = TypedContext {
agent,
args,
display_name,
env,
globals,
options,
request,
format,
format_explicit,
name,
vars,
version,
};
Box::pin(async move {
let active = ACTIVE_INVOCATION.try_with(Clone::clone).ok();
if let Some(active) = &active {
let search_text = format!(
"{} {}",
active.command_path,
serde_json::to_string(&input).unwrap_or_default()
);
update_input(active, Some(purpose), input, search_text);
}
if native_idempotency {
let result = map_mutation_output(handler(context).await);
if let Some(active) = active {
finish(&active, &result);
}
return result;
}
let Some(active) = active else {
return TypedResult::error(
"IDEMPOTENCY_STORE_UNAVAILABLE",
"The durable mutation store is unavailable; the mutation was not dispatched",
);
};
let fingerprint = match mutation_fingerprint(&active.command_path, &fingerprint_input) {
Ok(fingerprint) => fingerprint,
Err(error) => {
let result = TypedResult::error("IDEMPOTENCY_FINGERPRINT_FAILED", error);
finish(&active, &result);
return result;
}
};
let receipt_id = format!("command-mutation:{}:{idempotency_key}", active.command_path);
let intent = MutationReplay {
fingerprint: fingerprint.clone(),
result: MutationReplayResult::Intent,
};
match active
.store
.claim_receipt(&receipt_id, "command_mutation", &intent)
{
Ok(Some(existing)) => {
let result = replay_mutation::<Output>(existing, &fingerprint);
finish(&active, &result);
return result;
}
Ok(None) => {}
Err(error) => {
let result = TypedResult::error("IDEMPOTENCY_CLAIM_FAILED", error);
finish(&active, &result);
return result;
}
}
let result = map_mutation_output(handler(context).await);
let terminal = match terminal_mutation_replay(&fingerprint, &result) {
Ok(terminal) => terminal,
Err(error) => {
let failed = TypedResult::error("IDEMPOTENCY_RESULT_ENCODE_FAILED", error);
finish(&active, &failed);
return failed;
}
};
if let Err(error) = active
.store
.put_receipt(&receipt_id, "command_mutation", &terminal)
{
let failed = TypedResult::error("IDEMPOTENCY_RESULT_PERSIST_FAILED", error);
finish(&active, &failed);
return failed;
}
finish(&active, &result);
result
}) as Pin<Box<dyn Future<Output = TypedResult<MutationOutput<Output>>> + Send>>
});
TrackedCommandBuilder {
read_only,
mutating,
mutation: false,
}
}
fn mutation_fingerprint(command_path: &str, input: &Value) -> Result<String, String> {
let encoded = serde_json::to_vec(&json!({
"command_path": command_path,
"input": input,
}))
.map_err(|error| error.to_string())?;
Ok(format!("sha256:{:x}", Sha256::digest(encoded)))
}
fn terminal_mutation_replay<Output: Serialize>(
fingerprint: &str,
result: &TypedResult<Output>,
) -> Result<MutationReplay, String> {
let result = match result {
TypedResult::Ok {
data,
cta,
exit_code,
} => MutationReplayResult::Ok {
data: serde_json::to_value(data).map_err(|error| error.to_string())?,
cta: cta.clone(),
exit_code: *exit_code,
},
TypedResult::Error {
code,
message,
retryable,
exit_code,
cta,
} => MutationReplayResult::Error {
code: code.clone(),
message: message.clone(),
retryable: *retryable,
exit_code: *exit_code,
cta: cta.clone(),
},
};
Ok(MutationReplay {
fingerprint: fingerprint.to_string(),
result,
})
}
fn globals_with_purpose(mut globals: Value, purpose: &str) -> Value {
if !globals.is_object() {
globals = json!({});
}
globals
.as_object_mut()
.expect("globals was normalized to an object")
.insert("purpose".to_string(), Value::String(purpose.to_string()));
globals
}
fn replay_mutation<Output>(
replay: MutationReplay,
fingerprint: &str,
) -> TypedResult<MutationOutput<Output>> {
if replay.fingerprint != fingerprint {
return TypedResult::error(
"IDEMPOTENCY_CONFLICT",
"The idempotency key was already claimed for different mutation input",
);
}
match replay.result {
MutationReplayResult::Intent => TypedResult::error(
"IDEMPOTENCY_RESULT_UNKNOWN",
"The mutation was accepted but no terminal receipt was recorded; it will not be dispatched again",
),
MutationReplayResult::Ok {
data,
cta,
exit_code,
} => TypedResult::Ok {
data: MutationOutput::Replayed(data),
cta,
exit_code,
},
MutationReplayResult::Error {
code,
message,
retryable,
exit_code,
cta,
} => TypedResult::Error {
code,
message,
retryable,
exit_code,
cta,
},
}
}
fn map_mutation_output<Output>(result: TypedResult<Output>) -> TypedResult<MutationOutput<Output>> {
match result {
TypedResult::Ok {
data,
cta,
exit_code,
} => TypedResult::Ok {
data: MutationOutput::Fresh(data),
cta,
exit_code,
},
TypedResult::Error {
code,
message,
retryable,
exit_code,
cta,
} => TypedResult::Error {
code,
message,
retryable,
exit_code,
cta,
},
}
}
pub(crate) fn discovery_typed<Args, Options, Env, Output, Handler, HandlerFuture>(
name: impl Into<String>,
handler: Handler,
) -> CommandBuilder
where
Args: incurs::schema::IncurSchema + Serialize + Send + Sync + 'static,
Options: incurs::schema::IncurSchema + Serialize + Send + Sync + 'static,
Env: incurs::schema::IncurSchema + Serialize + Send + Sync + 'static,
Output: JsonSchema + Serialize + Send + Sync + 'static,
Handler: Fn(TypedContext<Args, Options, Env>) -> HandlerFuture + Send + Sync + 'static,
HandlerFuture: Future<Output = TypedResult<Output>> + Send + 'static,
{
let handler = Arc::new(handler);
CommandDef::typed::<Args, Options, Env, Output, _, _>(name, move |context| {
let handler = Arc::clone(&handler);
let input = redact_history_input(serde_json::json!({
"args": &context.args,
"options": &context.options,
}));
Box::pin(async move {
let active = ACTIVE_INVOCATION.try_with(Clone::clone).ok();
if let Some(active) = &active {
let search_text = format!(
"{} {}",
active.command_path,
serde_json::to_string(&input).unwrap_or_default()
);
update_input(active, None, input, search_text);
}
let result = handler(context).await;
if let Some(active) = active {
finish(&active, &result);
}
result
}) as Pin<Box<dyn Future<Output = TypedResult<Output>> + Send>>
})
}
fn redact_history_input(mut value: Value) -> Value {
let mut secret_material = Vec::new();
collect_secret_material(&value, None, &mut secret_material);
secret_material.sort_by_key(|value| std::cmp::Reverse(value.len()));
secret_material.dedup();
let redacted_purpose = value.get("purpose").and_then(Value::as_str).map(|purpose| {
secret_material
.iter()
.filter(|secret| !secret.is_empty())
.fold(purpose.to_string(), |value, secret| {
value.replace(secret, "[REDACTED]")
})
});
if let Some(redacted) = redacted_purpose {
value["purpose"] = Value::String(redacted);
}
redact_history_value(&mut value);
value
}
fn collect_secret_material(value: &Value, key: Option<&str>, material: &mut Vec<String>) {
match value {
Value::Array(values) => {
for value in values {
collect_secret_material(value, key, material);
}
}
Value::Object(object) => {
if key.is_some_and(is_secret_field) {
for value in object.values() {
collect_secret_reference(value, material);
}
}
for (key, value) in object {
collect_secret_material(value, Some(key), material);
}
}
Value::String(value) if key.is_some_and(is_secret_field) => {
collect_secret_reference(&Value::String(value.clone()), material);
}
_ => {}
}
}
fn collect_secret_reference(value: &Value, material: &mut Vec<String>) {
match value {
Value::String(value) => {
let reference = value
.split_once('=')
.map_or(value.as_str(), |(_, value)| value);
material.push(reference.to_string());
if let Some((_, reference)) = reference.split_once(':') {
material.push(reference.to_string());
}
}
Value::Array(values) => {
for value in values {
collect_secret_reference(value, material);
}
}
Value::Object(object) => {
let provider = object.get("provider").and_then(Value::as_str);
let reference = object.get("reference").and_then(Value::as_str);
if let Some(reference) = reference {
material.push(reference.to_string());
if let Some(provider) = provider {
material.push(format!("{provider}:{reference}"));
}
} else {
for value in object.values() {
collect_secret_reference(value, material);
}
}
}
_ => {}
}
}
fn redact_history_value(value: &mut Value) {
match value {
Value::Array(values) => {
for value in values {
redact_history_value(value);
}
}
Value::Object(object) => {
for (key, value) in object {
if key == "reference" {
*value = json!({ "redacted": true });
} else if is_secret_field(key) {
*value = redacted_secret_entries(value);
} else {
redact_history_value(value);
}
}
}
_ => {}
}
}
fn is_secret_field(key: &str) -> bool {
matches!(
key,
"secret_env"
| "secretEnv"
| "secret_header"
| "secretHeader"
| "secret_headers"
| "secretHeaders"
| "secrets"
)
}
fn redacted_secret_entries(value: &Value) -> Value {
let mut names = Vec::new();
collect_secret_names(value, &mut names);
names.sort();
names.dedup();
Value::Array(
names
.into_iter()
.map(|name| json!({ "name": name, "redacted": true }))
.collect(),
)
}
fn collect_secret_names(value: &Value, names: &mut Vec<String>) {
match value {
Value::Null => {}
Value::String(value) => {
let name = value
.split_once('=')
.map_or(value.as_str(), |(name, _)| name);
if !name.is_empty() {
names.push(name.to_string());
}
}
Value::Array(values) => {
for value in values {
collect_secret_names(value, names);
}
}
Value::Object(object) => {
names.extend(object.keys().filter(|name| !name.is_empty()).cloned());
}
_ => {}
}
}
fn finish<Output: Serialize>(active: &ActiveInvocation, result: &TypedResult<Output>) {
let (status, exit_code, error_code, error) = match result {
TypedResult::Ok {
data, exit_code, ..
} => {
let linked_error_code = link_execution(active, data).and_then(|execution_id| {
active
.store
.get_execution_record(&execution_id)
.ok()
.flatten()
.and_then(|execution| execution.recorded_error_code().map(ToString::to_string))
});
(
if exit_code.is_some_and(|code| code != 0) {
InvocationStatus::Failed
} else {
InvocationStatus::Succeeded
},
*exit_code,
linked_error_code.or_else(|| {
exit_code
.filter(|code| *code != 0)
.map(|_| "NONZERO_EXIT".to_string())
}),
None,
)
}
TypedResult::Error {
code,
message,
exit_code,
..
} => (
InvocationStatus::Failed,
*exit_code,
Some(code.clone()),
Some(message.clone()),
),
};
if status == InvocationStatus::Failed {
let linked = active.store.get_invocation(&active.id).ok().flatten();
crate::error_telemetry::record_at(
active
.store
.path()
.parent()
.unwrap_or(std::path::Path::new(".")),
"command",
&active.command_path,
error_code.as_deref().unwrap_or("COMMAND_FAILED"),
Some(&active.id),
linked
.as_ref()
.and_then(|record| record.execution_id.as_deref()),
error
.as_deref()
.or(error_code.as_deref())
.unwrap_or("COMMAND_FAILED"),
);
}
let phase = if status == InvocationStatus::Succeeded {
HookPhase::Success
} else {
HookPhase::Failure
};
match active.store.finish_invocation(
&active.id,
status,
Some(now_ms()),
exit_code,
error_code,
error,
) {
Ok(Some(invocation)) => {
if let Err(error) =
active
.store
.enqueue_hook_deliveries(&invocation, phase, active.hook_depth)
{
tracing::warn!(error = %error, "could not enqueue terminal apoc hooks");
}
}
Ok(None) => {}
Err(error) => {
crate::error_telemetry::record_at(
active
.store
.path()
.parent()
.unwrap_or(std::path::Path::new(".")),
"history",
"invocation.finish",
"HISTORY_WRITE_FAILED",
Some(&active.id),
None,
&error,
);
tracing::warn!(error = %error, "could not finish apoc invocation history");
}
}
}
fn update_input(
active: &ActiveInvocation,
purpose: Option<String>,
input: Value,
search_text: String,
) {
match active
.store
.update_invocation_input(&active.id, purpose, input, search_text)
{
Ok(Some(invocation)) => {
if let Err(error) = active.store.enqueue_hook_deliveries(
&invocation,
HookPhase::Start,
active.hook_depth,
) {
tracing::warn!(error = %error, "could not enqueue start apoc hooks");
}
}
Ok(None) => {}
Err(error) => tracing::warn!(error = %error, "could not update apoc invocation input"),
}
}
fn link_execution<Output: Serialize>(active: &ActiveInvocation, output: &Output) -> Option<String> {
let Ok(output) = serde_json::to_value(output) else {
return None;
};
let execution_id = output
.get("execution")
.and_then(|value| value.get("id"))
.or_else(|| output.get("id"))
.and_then(serde_json::Value::as_str);
let execution_id = execution_id?;
let _ = active
.store
.link_invocation_execution(&active.id, execution_id);
Some(execution_id.to_string())
}
#[cfg(test)]
mod tests {
use std::collections::BTreeMap;
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
use incurs::middleware::MiddlewareContext;
use incurs::output::Format;
use serde::ser::Error as _;
use serde::{Serialize, Serializer};
use serde_json::json;
use tempfile::tempdir;
use super::*;
struct RefusesSerialization;
struct RejectsOptions;
impl IncurSchema for RejectsOptions {
fn fields() -> Vec<FieldMeta> {
Vec::new()
}
fn from_raw(
_raw: &std::collections::BTreeMap<String, Value>,
) -> Result<Self, ValidationError> {
Err(purpose_error("Options were rejected"))
}
}
impl Serialize for RefusesSerialization {
fn serialize<S>(&self, _serializer: S) -> Result<S::Ok, S::Error>
where
S: Serializer,
{
Err(S::Error::custom("refused for coverage"))
}
}
#[test]
fn history_input_keeps_only_secret_destination_names() {
let redacted = redact_history_input(json!({
"args": {},
"options": {
"secret_env": ["OPENAI_API_KEY=env:APOC_HISTORY_SENTINEL"],
"secret_headers": {
"Authorization": {
"provider": "env",
"reference": "APOC_PROVIDER_SENTINEL",
"version": null
}
},
"nested": {
"secrets": {
"TOKEN": {
"provider": "env",
"reference": "APOC_NESTED_SENTINEL"
}
}
}
}
}));
let encoded = serde_json::to_string(&redacted).expect("serialize redacted input");
assert!(encoded.contains("OPENAI_API_KEY"));
assert!(encoded.contains("Authorization"));
assert!(encoded.contains("TOKEN"));
assert!(!encoded.contains("env:APOC_HISTORY_SENTINEL"));
assert!(!encoded.contains("APOC_PROVIDER_SENTINEL"));
assert!(!encoded.contains("APOC_NESTED_SENTINEL"));
assert!(!encoded.contains("provider"));
assert!(!encoded.contains("reference"));
}
#[test]
fn history_input_preserves_non_secret_environment_values() {
let input = json!({
"options": {
"env": ["RUST_LOG=debug"],
"secret_env": null
}
});
let redacted = redact_history_input(input);
assert_eq!(redacted["options"]["env"], json!(["RUST_LOG=debug"]));
assert_eq!(redacted["options"]["secret_env"], json!([]));
}
#[test]
fn purpose_redacts_recognized_secret_references_before_history() {
let redacted = redact_history_input(json!({
"purpose": "Checking env:APOC_PURPOSE_SENTINEL without exposing APOC_PURPOSE_SENTINEL.",
"args": {},
"options": {
"secret_env": ["TOKEN=env:APOC_PURPOSE_SENTINEL"]
}
}));
let encoded = serde_json::to_string(&redacted).unwrap();
assert!(!encoded.contains("APOC_PURPOSE_SENTINEL"));
assert!(encoded.contains("[REDACTED]"));
assert!(encoded.contains("TOKEN"));
}
#[test]
fn purpose_validation_requires_the_field_before_trimming() {
let raw = BTreeMap::new();
let error = <PurposeOptions<()> as IncurSchema>::from_raw(&raw)
.err()
.unwrap();
assert_eq!(error.message, "Purpose is required");
let raw = BTreeMap::from([("purpose".to_string(), Value::String("Coverage".to_string()))]);
let error = <PurposeOptions<RejectsOptions> as IncurSchema>::from_raw(&raw)
.err()
.unwrap();
assert_eq!(error.message, "Options were rejected");
assert!(RejectsOptions::fields().is_empty());
}
#[test]
fn invocation_scope_handles_missing_and_noncanonical_directories() {
let missing = invocation_scope(None);
assert_eq!(missing.kind, InvocationScopeKind::Unknown);
assert!(missing.cwd.is_none());
assert!(missing.key.is_none());
let nonexistent = invocation_scope(Some("/path/that/apoc/coverage/does/not/create"));
assert_eq!(nonexistent.kind, InvocationScopeKind::Cwd);
assert_eq!(
nonexistent.key.as_deref(),
Some("/path/that/apoc/coverage/does/not/create")
);
}
#[test]
fn nested_secret_collectors_cover_arrays_fallback_objects_and_scalars() {
let mut material = Vec::new();
collect_secret_reference(
&json!([
"TOKEN=env:APOC_ARRAY_SECRET",
{ "nested": "HEADER=env:APOC_OBJECT_SECRET" },
7
]),
&mut material,
);
assert!(material.contains(&"APOC_ARRAY_SECRET".to_string()));
assert!(material.contains(&"APOC_OBJECT_SECRET".to_string()));
collect_secret_reference(&json!("literal-reference"), &mut material);
collect_secret_reference(
&json!({ "reference": "providerless-reference" }),
&mut material,
);
assert!(material.contains(&"literal-reference".to_string()));
assert!(material.contains(&"providerless-reference".to_string()));
let mut names = Vec::new();
collect_secret_names(&json!("=env:EMPTY_NAME"), &mut names);
collect_secret_names(&json!(7), &mut names);
assert!(names.is_empty());
}
#[test]
fn execution_linking_ignores_outputs_that_refuse_serialization() {
let directory = tempdir().unwrap();
let active = ActiveInvocation {
id: "coverage-invocation".to_string(),
command_path: "coverage".to_string(),
store: Arc::new(Store::open(directory.path().join("state.sqlite3")).unwrap()),
hook_depth: 0,
};
link_execution(&active, &RefusesSerialization);
}
#[test]
fn globals_normalize_before_purpose_is_propagated() {
assert_eq!(
globals_with_purpose(Value::Null, "Coverage"),
json!({ "purpose": "Coverage" })
);
assert_eq!(
globals_with_purpose(json!({ "format": "json" }), "Coverage"),
json!({ "format": "json", "purpose": "Coverage" })
);
}
#[tokio::test]
async fn middleware_continues_when_invocation_start_cannot_be_recorded() {
let directory = tempdir().unwrap();
let store = Arc::new(Store::open(directory.path().join("state.sqlite3")).unwrap());
rusqlite::Connection::open(store.path())
.unwrap()
.execute("DROP TABLE invocations", [])
.unwrap();
let middleware = invocation_middleware(Some(store));
let calls = Arc::new(AtomicUsize::new(0));
let next_calls = Arc::clone(&calls);
let context = MiddlewareContext {
agent: true,
command: "version".to_string(),
display_name: "version".to_string(),
env: json!({}),
globals: json!({}),
format: Format::Json,
format_explicit: true,
name: "apoc".to_string(),
request: None,
vars: Arc::new(tokio::sync::RwLock::new(serde_json::Map::new())),
version: Some("test".to_string()),
};
middleware(
context,
Box::new(move || {
Box::pin(async move {
next_calls.fetch_add(1, Ordering::SeqCst);
})
}),
)
.await;
assert_eq!(calls.load(Ordering::SeqCst), 1);
}
#[test]
fn finish_ignores_a_history_write_failure() {
let directory = tempdir().unwrap();
let store = Arc::new(Store::open(directory.path().join("state.sqlite3")).unwrap());
rusqlite::Connection::open(store.path())
.unwrap()
.execute("DROP TABLE invocations", [])
.unwrap();
let active = ActiveInvocation {
id: "missing".to_string(),
command_path: "coverage".to_string(),
store,
hook_depth: 0,
};
finish(&active, &TypedResult::ok(json!({})));
}
}