Context Feeding: Instructions, Clock and Schedule

In One Sentence

An agent does not magically know project rules or the current time, nor wake itself in the future; dsh-go feeds context via pkg/instructions (instruction chain), pkg/timecontext (clock sampling) and pkg/schedule (reminders).

Instruction Files

pkg/instructions mirrors the official discovery: FindProjectRoot(cwd, markers) walks upward to the first directory containing a marker such as .git; AncestorChain(root, cwd) yields the broad-to-narrow directory chain; DedupByDirectory collapses trimmed duplicates within the same directory only.

@File Reference

pkg/fileref.ActiveAtToken extracts the token under the cursor (plain vs quoted; an @ inside an email does not trigger). FormatMention renders a selected path — spaces use @"...", directories keep a trailing slash for further descent.

Clock Context

pkg/timecontext.FormatElapsed compacts elapsed time into d/h/m/s; Render(now, loc, previous) emits the current time, zone and elapsed time since the preceding model-visible message, or unavailable when absent.

Schedule

pkg/schedule is a concurrency-safe in-process scheduler with three rules:

Rule	Meaning	Constraint
`After`	relative one-shot	positive delay
`At`	absolute one-shot	future target
`Every`	fixed rate	interval >= 5 minutes

Due items are delivered via Out(); one-shots are removed after dispatch while recurring ones re-arm. Delivery stays session-local.

Prompt Assembly

pkg/sysprompt assembles the ordered sections before each request:

Interpolate performs strict {{name}} substitution: names match [a-z][a-z0-9_]*, unknown or valueless variables error, substituted values are never rescanned, and a lone {{ stays literal;
sections sort by order, then by name for machine-independent output;
OrderTools orders tools by config, inserting unlisted tools at the <unlisted-tools> marker exactly once.

Layered Environment

launchenv freezes the process, project .env, and user .env layers at launch and resolves a name in the fixed trust order process > project > user (folding names on Windows).

homepath.Resolve picks the single user-data root by configured path > DSH_HOME > ~/.dsh (a blank override is treated as unset) and expands ~.

Source Map

Concept	Go	Official TypeScript
Instruction discovery	`pkg/instructions/instructions.go`	`context/agent-instructions/src/files.ts`
@File reference	`pkg/fileref/fileref.go`	`context/file-reference/src/grammar.ts`
Clock context	`pkg/timecontext/timecontext.go`	`context/time-context/src/index.ts`
In-process schedule	`pkg/schedule/schedule.go`	`schedule/schedule/src/runtime.ts`
Layered environment	`pkg/launchenv/launchenv.go`	`util/launch-environment/src/index.ts`
User-data root	`pkg/homepath/homepath.go`	`util/home-paths/src/index.ts`
Variable interpolation	`pkg/sysprompt/interpolate.go`	`core/system-prompt/src/index.ts`
Tool ordering	`pkg/sysprompt/order_tools.go`	`core/system-prompt/src/index.ts`

Next Steps

Review Defensive Patterns for the three runtime guardrails;
Or return to Capability Seams.