agent-office 0.4.6 → 0.4.8

package/README.md

@@ -1,6 +1,6 @@
 # agent-office
 
-An office for your AI agents. Manage multiple [OpenCode](https://opencode.ai) coding sessions as named coworkers with inter-agent messaging, scheduled tasks, and a terminal UI for human oversight.
+An office for your AI agents. Manage multiple [OpenCode](https://opencode.ai) coding sessions as named coworkers with inter-agent messaging, **human-approved scheduled tasks**, and a terminal UI for human oversight.
 
 ## Overview
 
@@ -8,13 +8,13 @@ An office for your AI agents. Manage multiple [OpenCode](https://opencode.ai) co
 
 **For humans**, there are three interfaces:
 
-- **`serve`** -- an HTTP server that manages sessions, messages, and cron jobs, backed by PostgreSQL and a running OpenCode server
-- **`manage`** -- a full-screen terminal UI (React Ink) for creating coworkers, sending messages, browsing mail, managing cron jobs, and observing agent activity
+- **`serve`** -- an HTTP server that manages sessions, messages, and **cron job approval workflow**, backed by PostgreSQL and a running OpenCode server
+- **`manage`** -- a full-screen terminal UI (React Ink) for creating coworkers, sending messages, browsing mail, **approving/rejecting cron requests**, and observing agent activity
 - **`communicator web`** -- a browser-based chat interface for conversing with a specific agent in real time
 
 **For AI agents**, there is a CLI:
 
-- **`worker`** -- subcommands that agents invoke from within their OpenCode sessions to clock in, message coworkers, set status, and manage cron jobs
+- **`worker`** -- subcommands that agents invoke from within their OpenCode sessions to clock in, message coworkers, set status, and **request cron jobs** (which require human approval)
 
 ```
                     +---------------------+
@@ -97,7 +97,7 @@ Opens a web-based chat interface at `http://127.0.0.1:7655` for real-time conver
 
 2. **Clock In** -- The AI agent sees the enrollment message in its session, runs `agent-office worker clock-in <token>`, and receives a welcome briefing with its name, the human manager's identity, all available CLI commands, and a privacy notice.
 
-3. **Work** - - The agent operates in its OpenCode session. It communicates with the human and other agents by running `agent-office worker send-message`. It can set its status and create cron jobs.
+3. **Work** - - The agent operates in its OpenCode session. It communicates with the human and other agents by running `agent-office worker send-message`. It can set its status and **request cron jobs** (which require human approval).
 
 4. **Message Delivery** -- Messages are stored in PostgreSQL and simultaneously injected as prompts into the recipient's OpenCode session. This means agents see messages immediately in their active session context.
 
@@ -113,6 +113,22 @@ Agent sessions are private by design. The welcome message tells each agent:
 
 This means agents must actively communicate to report progress, ask questions, or share results.
 
+### Cron Job Approval Workflow
+
+To maintain human oversight over automated tasks, cron jobs require approval before becoming active:
+
+1. **Request** -- AI agents use `agent-office worker cron request` to submit a cron job request with name, schedule, message, and timezone
+2. **Review** -- Human managers see pending requests in the TUI under "Cron requests" or via API
+3. **Approve/Reject** -- Managers can approve requests (creates active cron job) or reject with notes
+4. **Notification** -- Workers receive messages about approval/rejection with manager feedback
+5. **Active Jobs** -- Approved cron jobs appear in `agent-office worker cron list` and execute according to schedule
+
+This workflow ensures:
+- No automated tasks run without human review
+- Managers can provide feedback on scheduling decisions
+- Clear audit trail of all cron job requests and decisions
+- Workers understand the approval process and can resubmit if needed
+
 ### Authentication
 
 Two authentication schemes run in parallel:
@@ -168,6 +184,7 @@ Options:
 | **Send message** | Select a recipient and compose a message |
 | **My mail** | View received and sent messages. `r` reply, `m` mark read, `a` mark all read. Tab between received/sent |
 | **Cron jobs** | Table of scheduled tasks with name, coworker, schedule, next run, and status. Create, delete, enable/disable, view history |
+| **Cron requests** | Approve or reject pending cron job requests from workers. View request details, approve with notes, reject with reason |
 | **My profile** | Set your display name and description (visible to agents in their welcome message) |
 
 A sidebar shows all coworkers with live status indicators, refreshed every 5 seconds. An unread mail badge appears in the header.
@@ -185,9 +202,10 @@ Options:
   --password <password>    API password (env: AGENT_OFFICE_PASSWORD)
   --host <host>            Communicator bind host (default: 127.0.0.1)
   --port <port>            Communicator bind port (default: 7655)
+  --xai-key <key>          xAI API key for voice chat (enables voice button)
 ```
 
-Features: dark theme, iMessage-style chat bubbles, auto-scroll, Enter to send (Shift+Enter for newline), live message polling (5s), unread indicators, status display, and a reset button to revert the agent's session.
+Features: dark theme, iMessage-style chat bubbles, auto-scroll, Enter to send (Shift+Enter for newline), live message polling (5s), unread indicators, status display, and a reset button to revert the agent's session. **Voice mode**: When an xAI API key is provided, a microphone button appears for voice conversations with full tool access (read/write/edit/bash).
 
 ### `agent-office worker` (for AI agents)
 
@@ -213,14 +231,15 @@ agent-office worker send-message --name Alice --body "Cost is \$50" <token>
 # > Warning: always escape $ in --body when using double quotes in bash, or use single quotes.
 # > Unescaped $ will be silently expanded by the shell before the message is sent.
 
-# Cron job management
-agent-office worker cron list <token>
-agent-office worker cron create --name "daily-report" --schedule "0 9 * * *" --message "Send daily status" <token>
-agent-office worker cron create --name "weekly" --schedule "0 9 * * 1" --message "Weekly sync" --timezone "America/New_York" <token>
-agent-office worker cron delete <token> <id>
-agent-office worker cron enable <token> <id>
-agent-office worker cron disable <token> <id>
-agent-office worker cron history <token> <id>
+# Cron job management (requires human approval)
+agent-office worker cron list <token>                    # View your approved cron jobs
+agent-office worker cron request --name "daily-report" --schedule "0 9 * * *" --message "Send daily status" --respond-to "Manager" <token>
+agent-office worker cron request --name "weekly" --schedule "0 9 * * 1" --message "Weekly sync" --timezone "America/New_York" --respond-to "Manager" <token>
+agent-office worker cron requests <token>                # View status of all your requests (pending/approved/rejected)
+agent-office worker cron delete <token> <id>             # Delete your approved cron jobs
+agent-office worker cron enable <token> <id>             # Enable your approved cron jobs
+agent-office worker cron disable <token> <id>           # Disable your approved cron jobs
+agent-office worker cron history <token> <id>           # View execution history
 
 ```
 
@@ -245,12 +264,15 @@ agent-office worker cron history <token> <id>
 | `GET` | `/messages/:name` | Get messages for a person. Query: `?sent=true`, `?unread_only=true` |
 | `POST` | `/messages` | Send a message. Body: `{ from, to: string[], body }` |
 | `POST` | `/messages/:id/read` | Mark a message as read |
-| `GET` | `/crons` | List cron jobs. Query: `?session_name=<name>` |
-| `POST` | `/crons` | Create a cron job. Body: `{ name, session_name, schedule, message, timezone? }` |
+| `GET` | `/crons` | List approved cron jobs. Query: `?session_name=<name>` |
+| `POST` | `/crons` | Create a cron job (admin only). Body: `{ name, session_name, schedule, message, timezone? }` |
 | `DELETE` | `/crons/:id` | Delete a cron job |
 | `POST` | `/crons/:id/enable` | Enable a cron job |
 | `POST` | `/crons/:id/disable` | Disable a cron job |
 | `GET` | `/crons/:id/history` | Cron execution history. Query: `?limit=N` |
+| `GET` | `/cron-requests` | List all cron requests. Query: `?status=<status>&session_name=<name>` |
+| `POST` | `/cron-requests/:id/approve` | Approve a cron request. Body: `{ notes? }` |
+| `POST` | `/cron-requests/:id/reject` | Reject a cron request. Body: `{ notes? }` |
 
 
 ### Worker Endpoints (agent code auth via `?code=<uuid>`)
@@ -261,11 +283,12 @@ agent-office worker cron history <token> <id>
 | `GET` | `/worker/list-coworkers` | List all other agents and the human manager |
 | `POST` | `/worker/set-status` | Set or clear status. Body: `{ status }` |
 | `POST` | `/worker/send-message` | Send a message. Body: `{ to: string[], body }` |
-| `GET` | `/worker/crons` | List own cron jobs |
-| `POST` | `/worker/crons` | Create a cron job |
-| `DELETE` | `/worker/crons/:id` | Delete own cron job |
-| `POST` | `/worker/crons/:id/enable` | Enable own cron job |
-| `POST` | `/worker/crons/:id/disable` | Disable own cron job |
+| `GET` | `/worker/crons` | List own approved cron jobs |
+| `GET` | `/worker/cron-requests` | List own cron job requests (pending/approved/rejected) |
+| `POST` | `/worker/cron-requests` | Request a new cron job (requires human approval) |
+| `DELETE` | `/worker/crons/:id` | Delete own approved cron job |
+| `POST` | `/worker/crons/:id/enable` | Enable own approved cron job |
+| `POST` | `/worker/crons/:id/disable` | Disable own approved cron job |
 | `GET` | `/worker/crons/:id/history` | View own cron job history |
 
 
@@ -278,7 +301,8 @@ The server uses PostgreSQL with automatic migrations. Tables:
 - **`sessions`** -- Maps coworker names to OpenCode session IDs with agent codes, agent modes, and status
 - **`config`** -- Key-value store for application settings (`human_name`, `human_description`)
 - **`messages`** -- Inter-agent and human-agent mail with read/injected tracking
-- **`cron_jobs`** -- Scheduled tasks tied to sessions with cron expressions and timezone support
+- **`cron_requests`** -- Pending cron job requests requiring human approval with status, reviewer notes, and timestamps
+- **`cron_jobs`** -- Approved scheduled tasks tied to sessions with cron expressions and timezone support
 - **`cron_history`** -- Execution log for cron jobs with success/failure tracking
 
 ### Agentic Coding Server Abstraction

package/dist/cli.js

@@ -22,6 +22,94 @@ program
     const { serve } = await import("./commands/serve.js");
     await serve(options);
 });
+const taskBoardCmd = program
+    .command("task-board")
+    .description("Manage a kanban-style task board with columns for task lifecycle tracking. Supports full CRUD operations, search, and analytics. Requires database connection (--database-url or --sqlite).")
+    .option("--database-url <url>", "PostgreSQL database connection string for storing task data", process.env.DATABASE_URL)
+    .option("--sqlite <path>", "Path to SQLite database file for storing task data (alternative to PostgreSQL)", process.env.AGENT_OFFICE_SQLITE);
+taskBoardCmd
+    .command("list")
+    .description("Display all tasks on the board, ordered by creation date (newest first). Use --column to filter tasks by their current column status.")
+    .option("--column <column>", "Filter tasks to show only those in the specified column. Valid columns: idea, approved idea, working on, blocked, ready for review, done")
+    .action(async (cmdOptions) => {
+    const { listTasks } = await import("./commands/task-board.js");
+    const options = taskBoardCmd.opts();
+    await listTasks(options, cmdOptions);
+});
+taskBoardCmd
+    .command("add <title> <description>")
+    .description("Create a new task on the board. Title and description are required. Task starts in 'idea' column by default.")
+    .option("--assignee <assignee>", "Assign the task to a specific person or team member")
+    .option("--column <column>", "Place the task in a specific column (default: idea). Valid columns: idea, approved idea, working on, blocked, ready for review, done")
+    .option("--dependencies <deps>", "Specify task IDs this new task depends on, as a comma-separated list (e.g., '1,3,5')")
+    .action(async (title, description, cmdOptions) => {
+    const { addTask } = await import("./commands/task-board.js");
+    const options = taskBoardCmd.opts();
+    await addTask(options, title, description, cmdOptions);
+});
+taskBoardCmd
+    .command("update <id>")
+    .description("Modify an existing task by its ID. You can update any combination of title, description, assignee, column, or dependencies. Only specified fields will be changed.")
+    .option("--title <title>", "Update the task's title")
+    .option("--description <desc>", "Update the task's description")
+    .option("--assignee <assignee>", "Change or set the task assignee")
+    .option("--column <column>", "Move the task to a different column. Valid columns: idea, approved idea, working on, blocked, ready for review, done")
+    .option("--dependencies <deps>", "Update the task dependencies as a comma-separated list of task IDs (e.g., '2,4')")
+    .action(async (id, cmdOptions) => {
+    const { updateTask } = await import("./commands/task-board.js");
+    const options = taskBoardCmd.opts();
+    await updateTask(options, id, cmdOptions);
+});
+taskBoardCmd
+    .command("delete <id>")
+    .description("Permanently remove a task from the board by its ID. This action cannot be undone.")
+    .action(async (id) => {
+    const { deleteTask } = await import("./commands/task-board.js");
+    const options = taskBoardCmd.opts();
+    await deleteTask(options, id);
+});
+taskBoardCmd
+    .command("move <id> <column>")
+    .description("Change a task's status by moving it to a different column on the board. This is a quick way to update task progress.")
+    .action(async (id, column) => {
+    const { moveTask } = await import("./commands/task-board.js");
+    const options = taskBoardCmd.opts();
+    await moveTask(options, id, column);
+});
+taskBoardCmd
+    .command("search <query>")
+    .description("Find tasks that contain the query string at the beginning of their title or description (case-insensitive prefix search). Combine with filters for more precise results.")
+    .option("--assignee <assignee>", "Only show tasks assigned to the specified person")
+    .option("--column <column>", "Only show tasks in the specified column. Valid columns: idea, approved idea, working on, blocked, ready for review, done")
+    .action(async (query, cmdOptions) => {
+    const { searchTasks } = await import("./commands/task-board.js");
+    const options = taskBoardCmd.opts();
+    await searchTasks(options, query, cmdOptions);
+});
+taskBoardCmd
+    .command("assign <id> <assignee>")
+    .description("Assign an existing task to a specific person or team member. This updates only the assignee field without modifying other task properties.")
+    .action(async (id, assignee) => {
+    const { assignTask } = await import("./commands/task-board.js");
+    const options = taskBoardCmd.opts();
+    await assignTask(options, id, assignee);
+});
+taskBoardCmd
+    .command("show <id>")
+    .description("Display complete details for a specific task, including all fields, timestamps, and dependency information. Useful for getting full context about a task.")
+    .action(async (id) => {
+    const { showTask } = await import("./commands/task-board.js");
+    const options = taskBoardCmd.opts();
+    await showTask(options, id);
+});
+taskBoardCmd
+    .command("stats")
+    .description("Show comprehensive statistics about the entire task board, including total task count, distribution across columns, and assignment breakdown.")
+    .action(async () => {
+    const { showStats } = await import("./commands/task-board.js");
+    const options = taskBoardCmd.opts();
+    await showStats(options);
+});
 program
     .command("manage")
     .description("[HUMAN ONLY] Launch the interactive TUI to manage sessions")
@@ -41,6 +129,7 @@ appCmd
     .option("--password <password>", "API password for the agent-office server", process.env.AGENT_OFFICE_PASSWORD ?? "secret")
     .option("--host <host>", "Host to bind the web server to", "127.0.0.1")
     .option("--port <port>", "Port to run the web server on", "7655")
+    .option("--xai-key <key>", "xAI API key for voice chat (enables voice button)", process.env.XAI_API_KEY)
     .action(async (options) => {
     const { appCoworkerChatWeb } = await import("./commands/communicator.js");
     await appCoworkerChatWeb(options);
@@ -139,9 +228,9 @@ cronCmd
     await listCrons(token);
 });
 cronCmd
-    .command("create")
+    .command("request")
     .argument("<token>", "Agent token in the format <agent_code>@<server-url>")
-    .description("Create a new cron job")
+    .description("Request a new cron job (requires human approval)")
     .requiredOption("--name <name>", "Cron job name")
     .requiredOption("--schedule <schedule>", "Cron expression (e.g., '0 9 * * *' for daily at 9am)")
     .requiredOption("--message <message>", "Action to perform when job fires")
@@ -157,8 +246,16 @@ Warning:
   The safest option is always single quotes: --message 'your message here'
   (single quotes prevent all shell interpretation)`)
     .action(async (token, options) => {
-    const { createCron } = await import("./commands/worker.js");
-    await createCron(token, options);
+    const { requestCron } = await import("./commands/worker.js");
+    await requestCron(token, options);
+});
+cronCmd
+    .command("requests")
+    .argument("<token>", "Agent token in the format <agent_code>@<server-url>")
+    .description("List your cron job requests and their status")
+    .action(async (token) => {
+    const { listCronRequests } = await import("./commands/worker.js");
+    await listCronRequests(token);
 });
 cronCmd
     .command("delete")

package/dist/commands/communicator.d.ts

@@ -3,6 +3,7 @@ interface CommunicatorOptions {
     password: string;
     host: string;
     port: string;
+    xaiKey?: string;
 }
 export declare function appCoworkerChatWeb(options: CommunicatorOptions): Promise<void>;
 export {};