agentfootprint/dist/esm/adapters/code/fileName.d.ts

The explainable agent framework — backtrack a wrong answer to the exact context that caused it (evidence, not guesses). Built on footprintjs.

/**
 * The one file-name encoder both code adapters stage inputs under.
 *
 * A staged input's name is caller data landing in a filesystem — a local temp
 * directory for `localCodeRunner`, the sandbox's own disk for
 * `agentCoreCodeRunner`. Both turn it into ONE inert segment through this
 * function, so the same name lands under the same file name on either backend
 * and two names never become one file on either.
 */
/**
 * One caller-supplied name → one inert file-name segment, **without ever
 * folding two names into one file**.
 *
 * Separators cannot survive as a parent hop and `a/b` cannot become two
 * segments — the same law `artifacts/scopePath` states for scope tuples,
 * applied to the one other place caller strings become file names in this
 * package. But the old version got there by REPLACING every illegal character
 * with `_`, which meant `a/b.csv` and `a_b.csv` became the same file: the
 * second write clobbered the first's bytes, `stageInputs` answered two manifest
 * entries pointing at one path, and the model's code opened `a/b.csv` and read
 * whatever `a_b.csv` contained. Nothing failed. The computation was simply run
 * against the wrong dataset — which is the worst shape a data bug can take,
 * because the answer still looks like an answer. `.slice(0, 120)` folded the
 * same way for any two names agreeing on their first 120 characters.
 *
 * So this ENCODES instead of sanitising, in two arms whose outputs cannot meet
 * (the shape `safeSessionId` uses in `adapters/hosting/agentcore.ts`):
 *
 *   A. already one legal segment, not claiming to be an encoded name, and not
 *      dots-only → returned BYTE FOR BYTE. This is what keeps the fix from
 *      renaming anything that works today: `dataset.json`, `a_b.json`, every
 *      name `codeRunnerTool` derives from a declared argument, all land at
 *      exactly the path they landed at before.
 *   B. anything else → `_enc_` + an escaped form, where `_` is the escape
 *      character (`_` → `__`, any other illegal UTF-16 unit → `_uXXXX`). A
 *      decoder is a left inverse of that, which is what makes it injective.
 *
 * Arm A never starts with `_enc_` (excluded by construction) and every arm B
 * output does, so no name from one arm can collide with a name from the other.
 * Both arms produce ASCII with no `/`, no `\` and no NUL, so the path-hop law
 * the old version enforced is unchanged.
 */
export declare function safeFileName(raw: string): string;