Skip to content

feat(tools,scheduler): agent time-awareness — get_current_time tool + schedule add --run-at#6441

Merged
bug-ops merged 1 commit into
mainfrom
feat/issue-6361/agent-time-awareness
Jul 18, 2026
Merged

feat(tools,scheduler): agent time-awareness — get_current_time tool + schedule add --run-at#6441
bug-ops merged 1 commit into
mainfrom
feat/issue-6361/agent-time-awareness

Conversation

@bug-ops

@bug-ops bug-ops commented Jul 18, 2026

Copy link
Copy Markdown
Owner

Summary

  • Adds a chrono-free, mockable ClockSource abstraction (zeph-common), reusing the existing timestamp.rs RFC3339 formatting helpers instead of adding a chrono dependency.
  • Adds a get_current_time tool (zeph-tools) built on that clock, wired into all three production executor chains (CLI, daemon, ACP) via one shared clock instance.
  • Adds an opt-in periodic time-reminder injection (agent.time_reminder_enabled / agent.time_reminder_interval_requests, default off) into the volatile system-prompt block, counted in agent turn-cycles rather than literal per-model-requests (the mandated injection hook is architecturally unreachable at per-request granularity — see PR discussion).
  • Adds zeph schedule add --run-at <rfc3339>, exposing the existing TaskMode::OneShot scheduler primitive that previously had no CLI or tool-level entry point.
  • Fixes Scheduler::init() hydration, which previously skipped one-shot rows entirely (a CLI-added --run-at job never fired), and — once that was fixed — was found to discard the user's prompt via a Value::Null config on hydration (a kind="custom" one-shot job fired a generic fallback instead of the real prompt). Both are now fixed with regression tests.

Breaking change (pre-1.0.0)

zeph schedule add positional argument order changed from <CRON> <PROMPT> to <PROMPT> [CRON]. This was required by clap, which rejects an optional positional preceding a required one once --run-at made the cron argument optional. An old-order invocation now fails loudly on cron validation rather than silently misparsing. Documented in CHANGELOG.md.

Scope note

Spec .local/specs/070-agent-time-awareness/spec.md's US-004 (an agent-callable one-shot reminder-creation tool, as opposed to CLI-only) is deferred — the existing scheduler native tool already handles natural-language deferred/periodic scheduling and was left untouched. This PR fully delivers issue #6361's three literal asks (current-time tool, periodic reminder, one-shot CLI scheduling) and closes it.

Process note

This went through 2 rounds of architecture critique (a scheduler-hydration blocker was found and fixed before implementation started) and 2 rounds of implementation critique (a critical hydration prompt-loss defect and a significant clock-sharing gap were found post-implementation and fixed), plus clean independent security and performance audits.

Test plan

  • cargo +nightly fmt --check
  • cargo clippy --profile ci --workspace --all-targets --features "desktop,ide,server,chat,pdf,scheduler,testing" -- -D warnings
  • cargo nextest run --config-file .github/nextest.toml --workspace --features "desktop,ide,server,chat,pdf,scheduler" --lib --bins — 14323 passed, 0 failed
  • RUSTFLAGS="-D warnings" RUSTDOCFLAGS="--deny rustdoc::broken_intra_doc_links" cargo doc --no-deps --workspace --features "desktop,ide,server,chat,pdf,scheduler"
  • cargo test --doc --workspace --features "desktop,ide,server,chat,pdf,scheduler"
  • gitleaks protect --staged
  • Testing playbook: .local/testing/playbooks/agent-time-awareness.md
  • Coverage rows added to .local/testing/coverage-status.md

Closes #6361

@github-actions github-actions Bot added documentation Improvements or additions to documentation rust Rust code changes core zeph-core crate config Configuration file changes enhancement New feature or request size/XL Extra large PR (500+ lines) labels Jul 18, 2026
@bug-ops
bug-ops enabled auto-merge (squash) July 18, 2026 02:37
…un-at

Zeph had no mechanism for the agent to reason about wall-clock time:
no tool to query the current time, no time signal injected into the
system prompt, and the scheduler's internal one-shot primitive had no
CLI or tool-level entry point.

Adds a chrono-free, mockable ClockSource abstraction (zeph-common),
a get_current_time tool built on it (zeph-tools), an opt-in periodic
time-reminder injection into the volatile system prompt, and
`zeph schedule add --run-at <rfc3339>` exposing the existing
TaskMode::OneShot primitive. Also fixes scheduler hydration, which
previously skipped one-shot rows entirely and, once loaded, discarded
the user's prompt via a Value::Null config.

BREAKING CHANGE: `zeph schedule add` positional argument order is now
`<PROMPT> [CRON]` (was `<CRON> <PROMPT>`) — required by clap, which
forbids an optional positional preceding a required one once --run-at
made the cron argument optional. Pre-1.0.0, documented in CHANGELOG.

Closes #6361
@bug-ops
bug-ops force-pushed the feat/issue-6361/agent-time-awareness branch from 7f96e39 to cbdf1db Compare July 18, 2026 02:39
@bug-ops
bug-ops merged commit 01cd956 into main Jul 18, 2026
43 checks passed
@bug-ops
bug-ops deleted the feat/issue-6361/agent-time-awareness branch July 18, 2026 02:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

config Configuration file changes core zeph-core crate documentation Improvements or additions to documentation enhancement New feature or request rust Rust code changes size/XL Extra large PR (500+ lines)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

research(tools): no agent-callable current-time tool or one-shot wall-clock reminder

1 participant