Utilities#

Small helpers the connectors and the framework share.

Who an audit record names — one ladder, shared by every surface that records.

An audit record uses its identity twice: once as the actor field inside the envelope, and once as the <identity> path component of the spool directory var/spool/<identity> it is written into. If those two were resolved by separate code they would drift by a rung the first time one of them grew a fallback, and the record would start naming one actor while filing under another. This module is the single resolution, so both uses read the same answer by construction.

The ladder, most specific first:

  1. OSPREY_TERMINAL_USER — the multi-user deployment’s per-container user name. When it is set, a real person is behind the container.

  2. OSPREY_AUDIT_IDENTITY — what a container that hosts no single user is named instead: a framework service’s key, sidecar for auth. Rendered by the same derivation that names the audit mount path, so the writer’s path and the mounted path cannot diverge. Without this rung a shared or framework service container would file everything under the process account — osprey or root, which names nobody.

  3. The local account (getpass.getuser()) — the single-user laptop case, where the process account is the person.

  4. UNKNOWN_IDENTITY — an honest floor. An unresolvable identity must never cost the record.

Never the hostname. It looks like an identity and is not one: a host-network container reports the shared host’s name, so every service on the box would collide into one file, and a bridge-network container reports a random container id, so the same service would scatter across a new file per restart.

``OSPREY_AUDIT_IDENTITY`` must never join a scrub list. An executor sandbox and a notebook kernel are severed from most of the environment they inherit, and they resolve their own record directory through this ladder — the audit directory and the per-identity control-state directory both. Rung 2 is the only rung that survives that severing inside a container: the OSPREY_TERMINAL_ prefix is scrubbed by design, and the process account there names osprey or root. Drop this one variable from a child and the child writes its records and reads its narrowing under a name no reader looks for, which is worse than either failing or being scrubbed — it is silently answering about somebody else.

Stdlib only, and a leaf of this package. It is read where osprey cannot be imported at all — connector-host children, executor sandboxes, notebook kernels — and it is imported from mcp_server, from the interface apps and from the services, where an osprey import here would risk a cycle between those packages. osprey_connectors.identity re-exports every name below, so the historical import path costs no second implementation.

osprey_connectors.identity.AUDIT_IDENTITY_ENV: str = 'OSPREY_AUDIT_IDENTITY'#

The identity of a container that hosts no single user — a framework service’s key, or sidecar for auth. Rendered into every containerized service’s environment: by the same derivation that names its audit mount. Audit-critical in both directions: it is stripped from every MCP server spec’s declared env:, so that no spec can repoint another service’s records at itself, and never from a child’s inherited process environment, which is where a sandbox or a kernel reads it - see the never-scrub rule above.

osprey_connectors.identity.IDENTITY_ENV_LADDER: tuple[str, ...] = ('OSPREY_TERMINAL_USER', 'OSPREY_AUDIT_IDENTITY')#

The environment rungs, in the order they are consulted. Exposed so a test or a drift check can assert the order rather than re-encode it.

osprey_connectors.identity.TERMINAL_USER_ENV: str = 'OSPREY_TERMINAL_USER'#

The multi-user deployment’s per-container user name. Spelled locally rather than imported from interfaces.common_middleware, which owns the same constant for URL-prefix purposes: importing it would cost this module its leaf property, and the name is a deployment contract that does not move.

osprey_connectors.identity.UNKNOWN_IDENTITY: str = 'unknown'#

What a record names when no rung resolves. A slim image often has no pwd entry for its uid, which is normal rather than exceptional, so this is a routine outcome and not an error path.

osprey_connectors.identity.acting_identity()[source]#

Return the identity an audit record should carry, per the module ladder.

Reads the environment on every call rather than caching at import: the markers are set per process by compose and by the entrypoint, and a value frozen at import time would be whatever the first importer happened to see.

Takes no arguments on purpose. A caller-supplied override would be a second ladder — the exact drift this module exists to prevent — so every surface gets the same answer from the same source or none at all.

Never raises: getpass.getuser() raises KeyError (Python 3.12 and earlier) or OSError (3.13+) for a uid with no passwd entry, which is ordinary in a slim container, and any other failure is equally not worth an audit record. Every failure lands on UNKNOWN_IDENTITY.

Return type:

str

osprey_connectors.identity.usable_identity(value)[source]#

Return value stripped, or "" if it cannot serve as an identity.

A rung must produce a value that works for both uses or it has not produced an identity at all. Empty and whitespace-only values are the unset case spelled differently — a rendered-but-blank environment: entry, an env var exported as "". Values carrying a path separator or naming a relative directory are rejected because the same string becomes a directory name under var/spool/, where ../elsewhere would file one service’s records into another’s mount.

Rejection is deliberately narrow: it covers what breaks path semantics and nothing else. A stricter character allowlist would turn a legitimate account name into UNKNOWN_IDENTITY, which loses more than it protects.

Return type:

str

Declarative relative timestamps, resolved against an anchor at load time.

Demo and seed data (simulation scenario bundles and their narratives, seed files the generic ARIEL adapter reads) express timestamps relative to “now” — {days_ago, time} — rather than as absolute dates. They resolve to concrete datetimes at the moment data enters the system (osprey sim apply and the deploy-time seed for scenario narratives; osprey ariel ingest/quickstart for the generic adapter), so the data always lands at a recent, deterministic wall-clock position without ever mutating the source file at build time.

This is the single shared primitive, living in osprey_connectors so neither the simulation engine nor the ARIEL ingestion layer depends on the other.

class osprey_connectors.relative_time.RelativeTimestamp(days_ago, time)[source]#

Bases: object

A timestamp expressed relative to an apply-/ingest-time anchor.

days_ago is a whole-day shift back from the anchor date; time pins the resolved time-of-day (tz-naive local), so hardcoded prose clock times in an entry body stay consistent with the resolved timestamp.

days_ago: int#
time: time#
__init__(days_ago, time)#
osprey_connectors.relative_time.resolve_relative_timestamp(spec, now)[source]#

Resolve a relative timestamp against an anchor now.

Shifts now back spec.days_ago whole calendar days and pins the resolved time-of-day to spec.time. The shift is computed on the date component, so it is DST-safe (it counts calendar days, not 24-hour spans) and the resolved wall-clock time is exactly spec.time regardless of any DST transition between the two dates. The result carries now’s tzinfo (naive in, naive out).

Parameters:
  • spec (RelativeTimestamp) – The relative timestamp (whole-day offset plus time-of-day).

  • now (datetime) – The anchor instant. For scenario bundles this is the shared apply-time T0 (so narrative and telemetry resolve against one clock); for generic ingestion it is the ingest-time “now”.

Returns:

The resolved timestamp, with the same tzinfo as now.

Return type:

datetime

Replace a file whole: the one way OSPREY rewrites a file in place.

Every writer that rewrites a file calls atomic_replace(), so a reader sees the old file or the new one and never a mix, a crash never leaves half a file, and the file’s mode never depends on the process umask.

It also states, once, the shape of a group-shared location: a place written and read under several uids that reach one another through the setgid group of its directory. Such a directory is SHARED_DIR_MODE, created through ensure_shared_dir(); a file in it is SHARED_FILE_MODE, and a lock in it SHARED_LOCK_MODE:

<location>/             2770  setgid: every entry below takes its group
  <identity>/           2770  every level a writer creates, set exactly
    record.json         0640  read by the group, written by its owner
    record.json.lock    0660  taken by every writer in the group

This module uses the standard library only. The Claude Code hooks run under the system python3 and import nothing from OSPREY, so they ship this file beside them as .claude/hooks/osprey_safety_file.py, a byte-identical copy that tests/hooks/test_osprey_safety_file.py holds equal to this one. A change is made here and copied there. That hooks catalog row is also the copy the build stages beside the control-identity script that containers run by path, so the byte pin keeps that copy equal to this module too.

osprey_connectors.safety_file.SHARED_DIR_MODE = 1528#

A directory of a group-shared location. Setgid, so every entry created in it takes its group whatever uid created it; group-write, so a writer under one uid can replace what another wrote; nothing for other, which would let it list the names inside.

osprey_connectors.safety_file.SHARED_FILE_MODE = 416#

written by its owner, read through the directory’s group by the uids that never coordinate with that owner.

Type:

A file in a group-shared location

osprey_connectors.safety_file.SHARED_LOCK_MODE = 432#

whichever writer creates it first sets its mode, and every writer in the group has to be able to open it.

Type:

A lock file in a group-shared location

osprey_connectors.safety_file.atomic_replace(path, data, *, mode, sync='required')[source]#

Replace the file at path with data, whole or not at all.

data goes into a temporary file in the same directory, created here under a hidden name nobody can predict (.<name>.<random>.tmp), so it is never an existing file or a link someone planted; it is given mode (whatever the umask), synced, and renamed over path, and the directory is synced after the rename. A reader sees the old file or the new one, never a mix. When anything fails, the temporary file is removed and the exception propagates.

sync="required" raises when the disk refuses to flush the file; sync="best_effort" carries on without the flush and still replaces the file.

Choose sync="required" exactly when the caller surfaces the failure to someone who can retry (an operator, a CLI, a build); choose sync="best_effort" when the caller swallows the error, because then a file replaced without its flush is more durable than the old file kept.

osprey_connectors.safety_file.ensure_shared_dir(directory, *, modes='required')[source]#

Create directory and the levels above it at SHARED_DIR_MODE.

Every level this call creates — the levels above the leaf as much as the leaf — is set to exactly SHARED_DIR_MODE rather than merely widened: mkdir honours the umask and drops the setgid bit, so a level left as it made it is 0755 (other lists the names inside) or, under umask 077, 0700 (the group cannot reach the files inside at all). A level that already exists is not this writer’s: deployment provisioned it, or another uid made it, and it keeps the mode it has. The levels are made one at a time from the top, so a level another writer makes first, between the look and the make, is left to that writer while the levels this call does make still get their mode. A mode is never set through a symbolic link.

modes="required" raises when a mode cannot be set; modes="best_effort" keeps the directory as made, for a writer whose record is worth more in a narrower directory than not written at all.

Raises:

OSError – A level could not be created, or (modes="required") a level’s mode could not be set, a link included (errno.ELOOP).