Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

feat(cli): auto-resolve --agent_id from ALOOK_AGENT_ID env var

Gus5083a1442307
diff --git a/src/app/test/services.test.ts b/src/app/test/services.test.ts
index c4faff754..3a8baf42a 100644
--- a/src/app/test/services.test.ts
+++ b/src/app/test/services.test.ts
@@ -28,7 +28,7 @@ describe("services", () => {
it("returns false when no pid file exists", async () => {
const { isRunning } = await import("../src/lib/services.js");
expect(isRunning()).toBe(false);
- });
+ }, 15_000);
it("returns false when all pids are dead", async () => {
const { writePids } = await import("../src/lib/pid.js");
diff --git a/src/cli/README.md b/src/cli/README.md
index 3eeb0da88..f0832d613 100644
--- a/src/cli/README.md
+++ b/src/cli/README.md
@@ -33,11 +33,11 @@ The daemon runs in the background, polling for tasks and dispatching them to you
| `status` | Show registration status and linked workspace |
| `daemon start` | Start the background daemon |
| `daemon stop` | Stop the daemon |
-| `email pull --agent_id <id>` | Download agent emails |
-| `email send --agent_id <id> --to <addr> --subject "..." --body-file <path>` | Send an email |
-| `calendar set --agent_id <id> --event_title "..." --datetime <YYYY-MM-DDTHH:MM>` | Create a scheduled event |
-| `issue create --agent_id <id> --title "..."` | Create and dispatch an issue |
-| `sync upload-artifact --agent_id <id> --conversation_id <id> --file <path>` | Upload a file artifact |
+| `email pull` | Download agent emails |
+| `email send --to <addr> --subject "..." --body-file <path>` | Send an email |
+| `calendar set --event_title "..." --datetime <YYYY-MM-DDTHH:MM>` | Create a scheduled event |
+| `issue create --title "..."` | Create and dispatch an issue |
+| `sync upload-artifact --conversation_id <id> --file <path>` | Upload a file artifact |
| `config show` | Show current configuration |
| `update` | Update CLI to the latest version |
| `version` | Print CLI version |
@@ -60,19 +60,19 @@ alook daemon status # Check if the daemon is running
<summary><strong>email</strong> — pull, send, reply, forward, and manage sender whitelist</summary>
```bash
-alook email pull --agent_id <id> # Download inbox
-alook email pull --agent_id <id> --status unread # Unread only
-alook email pull --agent_id <id> --folder sent # Sent emails
-alook email set --agent_id <id> --email_id <id> --status read # Mark as read
+alook email pull # Download inbox
+alook email pull --status unread # Unread only
+alook email pull --folder sent # Sent emails
+alook email set --email_id <id> --status read # Mark as read
-alook email send --agent_id <id> --to <addr> --subject "Hi" --body-file body.html
+alook email send --to <addr> --subject "Hi" --body-file body.html
alook email send ... --in-reply-to <email_id> # Reply to a thread
alook email send ... --attachment report.pdf # Attach a file
-alook email forward --agent_id <id> --email_id <id> --to <addr> --note "FYI"
+alook email forward --email_id <id> --to <addr> --note "FYI"
-alook email whitelist list --agent_id <id> # List allowed senders
-alook email whitelist add --agent_id <id> <email> # Allow a sender
-alook email whitelist delete --agent_id <id> <email> # Remove a sender
+alook email whitelist list # List allowed senders
+alook email whitelist add <email> # Allow a sender
+alook email whitelist delete <email> # Remove a sender
```
Options: `--from <addr>` to send from a custom mailbox, `--limit <n>` / `--offset <n>` for pagination, `--json` for machine-readable output.
@@ -85,13 +85,13 @@ Options: `--from <addr>` to send from a custom mailbox, `--limit <n>` / `--offse
When an event fires, a new task is dispatched to the agent with the event title as the prompt.
```bash
-alook calendar set --agent_id <id> --event_title "Daily standup" --datetime 2026-05-16T09:00
+alook calendar set --event_title "Daily standup" --datetime 2026-05-16T09:00
alook calendar set ... --repeat 1week --repeat_stop_date 2026-12-31
-alook calendar list --agent_id <id> # List upcoming events
-alook calendar show --agent_id <id> --event_id <id> # Show full detail
-alook calendar update --agent_id <id> --event_id <id> --datetime 2026-05-17T10:00
-alook calendar delete --agent_id <id> --event_id <id>
+alook calendar list # List upcoming events
+alook calendar show --event_id <id> # Show full detail
+alook calendar update --event_id <id> --datetime 2026-05-17T10:00
+alook calendar delete --event_id <id>
```
Datetime is always local time (`YYYY-MM-DDTHH:MM`). Repeat intervals: `1hour`, `1day`, `1week`, `1month`, etc.
@@ -102,14 +102,14 @@ Datetime is always local time (`YYYY-MM-DDTHH:MM`). Repeat intervals: `1hour`, `
<summary><strong>issue</strong> — create and manage issues assigned to agents</summary>
```bash
-alook issue create --agent_id <id> --title "Fix login bug"
-alook issue create --agent_id <id> --title "Refactor auth" --body-file spec.md
-
-alook issue list --agent_id <id> # Active issues
-alook issue list --agent_id <id> --completed # Completed/closed issues
-alook issue show --agent_id <id> --issue_id <id> # Full detail + conversation
-alook issue update --agent_id <id> --issue_id <id> --status done
-alook issue comment --agent_id <id> --issue_id <id> --body "Looks good"
+alook issue create --title "Fix login bug"
+alook issue create --title "Refactor auth" --body-file spec.md
+
+alook issue list # Active issues
+alook issue list --completed # Completed/closed issues
+alook issue show --issue_id <id> # Full detail + conversation
+alook issue update --issue_id <id> --status done
+alook issue comment --issue_id <id> --body "Looks good"
```
Statuses: `todo`, `in_progress`, `review`, `done`, `closed`, `canceled`, `failed`.
@@ -137,6 +137,7 @@ Config is stored at `~/.alook/config.json` and includes:
```
--server <url> Override server URL
--profile <name> Use a specific config profile
+--agent_id <id> Override agent ID (default: $ALOOK_AGENT_ID env var)
```
## Requirements
diff --git a/src/cli/commands/calendar.test.ts b/src/cli/commands/calendar.test.ts
index bb8a5f9e3..44c048929 100644
--- a/src/cli/commands/calendar.test.ts
+++ b/src/cli/commands/calendar.test.ts
@@ -13,11 +13,11 @@ describe("calendarCommand", () => {
expect(names).toContain("delete");
});
- it("calendar set requires --agent_id, --event_title, --datetime", () => {
+ it("calendar set requires --event_title, --datetime; --agent_id is optional (env fallback)", () => {
const set = cmd.commands.find((c) => c.name() === "set")!;
const opts = (set as unknown as { options: { long: string; mandatory?: boolean }[] }).options;
const mandatory = opts.filter((o) => o.mandatory).map((o) => o.long);
- expect(mandatory).toContain("--agent_id");
+ expect(mandatory).not.toContain("--agent_id");
expect(mandatory).toContain("--event_title");
expect(mandatory).toContain("--datetime");
// not mandatory
@@ -41,29 +41,30 @@ describe("calendarCommand", () => {
expect(descOpt?.mandatory).not.toBe(true);
});
- it("calendar list requires --agent_id; supports --future_days and --past_days", () => {
+ it("calendar list has optional --agent_id (env fallback); supports --future_days and --past_days", () => {
const list = cmd.commands.find((c) => c.name() === "list")!;
const opts = (list as unknown as { options: { long: string; mandatory?: boolean }[] }).options;
const mandatory = opts.filter((o) => o.mandatory).map((o) => o.long);
- expect(mandatory).toContain("--agent_id");
+ expect(mandatory).not.toContain("--agent_id");
const longs = opts.map((o) => o.long);
+ expect(longs).toContain("--agent_id");
expect(longs).toContain("--future_days");
expect(longs).toContain("--past_days");
});
- it("calendar show requires --agent_id and --event_id", () => {
+ it("calendar show requires --event_id; --agent_id is optional (env fallback)", () => {
const show = cmd.commands.find((c) => c.name() === "show")!;
const opts = (show as unknown as { options: { long: string; mandatory?: boolean }[] }).options;
const mandatory = opts.filter((o) => o.mandatory).map((o) => o.long);
- expect(mandatory).toContain("--agent_id");
+ expect(mandatory).not.toContain("--agent_id");
expect(mandatory).toContain("--event_id");
});
- it("calendar update requires --agent_id and --event_id and accepts mutating flags as optional", () => {
+ it("calendar update requires --event_id; --agent_id is optional (env fallback); accepts mutating flags", () => {
const update = cmd.commands.find((c) => c.name() === "update")!;
const opts = (update as unknown as { options: { long: string; mandatory?: boolean }[] }).options;
const mandatory = opts.filter((o) => o.mandatory).map((o) => o.long);
- expect(mandatory).toContain("--agent_id");
+ expect(mandatory).not.toContain("--agent_id");
expect(mandatory).toContain("--event_id");
const longs = opts.map((o) => o.long);
for (const flag of [
@@ -81,11 +82,11 @@ describe("calendarCommand", () => {
}
});
- it("calendar delete requires --agent_id and --event_id", () => {
+ it("calendar delete requires --event_id; --agent_id is optional (env fallback)", () => {
const del = cmd.commands.find((c) => c.name() === "delete")!;
const opts = (del as unknown as { options: { long: string; mandatory?: boolean }[] }).options;
const mandatory = opts.filter((o) => o.mandatory).map((o) => o.long);
- expect(mandatory).toContain("--agent_id");
+ expect(mandatory).not.toContain("--agent_id");
expect(mandatory).toContain("--event_id");
});
diff --git a/src/cli/commands/calendar.ts b/src/cli/commands/calendar.ts
index 6646bf300..1f12311e6 100644
--- a/src/cli/commands/calendar.ts
+++ b/src/cli/commands/calendar.ts
@@ -3,6 +3,7 @@ import { APIClient } from "../lib/client.js";
import { loadCLIConfigForProfile } from "../lib/config.js";
import { printJSON } from "../lib/output.js";
import { cmdPrefix } from "../lib/env.js";
+import { resolveAgentId } from "../lib/flags.js";
interface CalendarEventResponse {
id: string;
@@ -97,7 +98,7 @@ export function calendarCommand(): Command {
cmd
.command("set")
.description("Create a calendar event")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.requiredOption("--event_title <title>", "Event title (used as the task prompt)")
.requiredOption(
"--datetime <iso>",
@@ -111,9 +112,10 @@ export function calendarCommand(): Command {
)
.option("--json", "Output as JSON")
.action(async (opts, command) => {
+ const agentId = resolveAgentId(opts);
const { serverUrl, token, workspaceId } = resolveClientOpts(
command,
- opts.agent_id
+ agentId
);
const client = new APIClient(serverUrl, token, workspaceId);
@@ -137,7 +139,7 @@ export function calendarCommand(): Command {
}
const body: Record<string, unknown> = {
- agent_id: opts.agent_id,
+ agent_id: agentId,
title: opts.event_title,
scheduled_at: scheduledAt,
};
@@ -168,14 +170,15 @@ export function calendarCommand(): Command {
cmd
.command("list")
.description("List calendar events for an agent")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.option("--future_days <n>", "Include events scheduled in the next N days", "30")
.option("--past_days <n>", "Include events scheduled in the past N days", "0")
.option("--json", "Output as JSON")
.action(async (opts, command) => {
+ const agentId = resolveAgentId(opts);
const { serverUrl, token, workspaceId } = resolveClientOpts(
command,
- opts.agent_id
+ agentId
);
const client = new APIClient(serverUrl, token, workspaceId);
@@ -189,7 +192,7 @@ export function calendarCommand(): Command {
try {
const events = await client.getJSON<CalendarEventResponse[]>(
- `/api/calendar?agentId=${encodeURIComponent(opts.agent_id)}&from=${encodeURIComponent(from)}&to=${encodeURIComponent(to)}`
+ `/api/calendar?agentId=${encodeURIComponent(agentId)}&from=${encodeURIComponent(from)}&to=${encodeURIComponent(to)}`
);
if (opts.json) {
printJSON(events);
@@ -217,13 +220,14 @@ export function calendarCommand(): Command {
cmd
.command("show")
.description("Show the full detail of a single calendar event")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.requiredOption("--event_id <id>", "Event ID")
.option("--json", "Output as JSON")
.action(async (opts, command) => {
+ const agentId = resolveAgentId(opts);
const { serverUrl, token, workspaceId } = resolveClientOpts(
command,
- opts.agent_id
+ agentId
);
const client = new APIClient(serverUrl, token, workspaceId);
@@ -231,9 +235,9 @@ export function calendarCommand(): Command {
const ev = await client.getJSON<CalendarEventResponse>(
`/api/calendar/${opts.event_id}`
);
- if (ev.agent_id !== opts.agent_id) {
+ if (ev.agent_id !== agentId) {
console.error(
- `Error: event ${ev.id} does not belong to agent ${opts.agent_id}`
+ `Error: event ${ev.id} does not belong to agent ${agentId}`
);
process.exit(1);
}
@@ -251,7 +255,7 @@ export function calendarCommand(): Command {
cmd
.command("update")
.description("Update fields on an existing calendar event")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.requiredOption("--event_id <id>", "Event ID")
.option("--event_title <title>", "New event title (task prompt)")
.option("--description <text>", "New description text")
@@ -320,9 +324,10 @@ export function calendarCommand(): Command {
process.exit(1);
}
+ const agentId = resolveAgentId(opts);
const { serverUrl, token, workspaceId } = resolveClientOpts(
command,
- opts.agent_id
+ agentId
);
const client = new APIClient(serverUrl, token, workspaceId);
@@ -331,9 +336,9 @@ export function calendarCommand(): Command {
`/api/calendar/${opts.event_id}`,
body
);
- if (updated.agent_id !== opts.agent_id) {
+ if (updated.agent_id !== agentId) {
console.error(
- `Error: event ${updated.id} does not belong to agent ${opts.agent_id}`
+ `Error: event ${updated.id} does not belong to agent ${agentId}`
);
process.exit(1);
}
@@ -351,12 +356,13 @@ export function calendarCommand(): Command {
cmd
.command("delete")
.description("Delete a calendar event")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.requiredOption("--event_id <id>", "Event ID")
.action(async (opts, command) => {
+ const agentId = resolveAgentId(opts);
const { serverUrl, token, workspaceId } = resolveClientOpts(
command,
- opts.agent_id
+ agentId
);
const client = new APIClient(serverUrl, token, workspaceId);
diff --git a/src/cli/commands/email.test.ts b/src/cli/commands/email.test.ts
index 340ebfaa3..a39c0b9d1 100644
--- a/src/cli/commands/email.test.ts
+++ b/src/cli/commands/email.test.ts
@@ -276,10 +276,10 @@ describe("email send subcommand shape", () => {
expect(send).toBeDefined();
});
- it("requires --agent_id, --to, --subject, --body-file", () => {
+ it("requires --to, --subject, --body-file; --agent_id is optional (env fallback)", () => {
const opts = (send as unknown as { options: { long: string; mandatory?: boolean }[] }).options;
const mandatory = opts.filter((o) => o.mandatory).map((o) => o.long);
- expect(mandatory).toContain("--agent_id");
+ expect(mandatory).not.toContain("--agent_id");
expect(mandatory).toContain("--to");
expect(mandatory).toContain("--subject");
expect(mandatory).toContain("--body-file");
@@ -598,10 +598,10 @@ describe("email forward subcommand shape", () => {
expect(forward).toBeDefined();
});
- it("requires --agent_id, --email_id, --to", () => {
+ it("requires --email_id, --to; --agent_id is optional (env fallback)", () => {
const opts = (forward as unknown as { options: { long: string; mandatory?: boolean }[] }).options;
const mandatory = opts.filter((o) => o.mandatory).map((o) => o.long);
- expect(mandatory).toContain("--agent_id");
+ expect(mandatory).not.toContain("--agent_id");
expect(mandatory).toContain("--email_id");
expect(mandatory).toContain("--to");
});
@@ -967,12 +967,14 @@ describe("whitelist command registration", () => {
expect(subNames).toContain("delete");
});
- it("--agent_id is required on all three subcommands", () => {
+ it("--agent_id is optional on all three subcommands (env fallback)", () => {
for (const name of ["list", "add", "delete"]) {
const sub = whitelistCmd.commands.find((c) => c.name() === name)!;
const opts = (sub as unknown as { options: { long: string; mandatory?: boolean }[] }).options;
const mandatory = opts.filter((o) => o.mandatory).map((o) => o.long);
- expect(mandatory).toContain("--agent_id");
+ const longs = opts.map((o) => o.long);
+ expect(longs).toContain("--agent_id");
+ expect(mandatory).not.toContain("--agent_id");
}
});
diff --git a/src/cli/commands/email.ts b/src/cli/commands/email.ts
index 21f05aa6a..3e20a1824 100644
--- a/src/cli/commands/email.ts
+++ b/src/cli/commands/email.ts
@@ -8,6 +8,7 @@ import { printJSON, printTable } from "../lib/output.js";
import { cmdPrefix } from "../lib/env.js";
import { tempDir } from "../lib/platform.js";
import { createLogger } from "../lib/logger.js";
+import { resolveAgentId } from "../lib/flags.js";
const log = createLogger({ module: "email" });
@@ -135,7 +136,7 @@ export function emailCommand(): Command {
cmd
.command("pull")
.description("Download and parse emails to /tmp/alook-emails/{workspaceId}/{agentId}/")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.option("--status <status>", "Filter by status (unread, read, archived)")
.option("--folder <folder>", "Email folder (inbox, sent, untrust)")
.option("--limit <n>", "Maximum number of emails to download")
@@ -143,7 +144,8 @@ export function emailCommand(): Command {
.option("--workspace <id>", "Workspace ID")
.option("--json", "Output as JSON instead of files")
.action(async (opts, command) => {
- const { serverUrl, token, workspaceId } = resolveClientOpts(command, { workspace: opts.workspace, agentId: opts.agent_id });
+ const agentId = resolveAgentId(opts);
+ const { serverUrl, token, workspaceId } = resolveClientOpts(command, { workspace: opts.workspace, agentId });
const client = new APIClient(serverUrl, token, workspaceId);
if (opts.status && !VALID_STATUSES.includes(opts.status)) {
@@ -176,10 +178,10 @@ export function emailCommand(): Command {
}
}
- const emailDir_base = join(EMAIL_BASE, workspaceId, opts.agent_id);
+ const emailDir_base = join(EMAIL_BASE, workspaceId, agentId);
try {
- let query = `/api/email?agentId=${opts.agent_id}`;
+ let query = `/api/email?agentId=${agentId}`;
if (opts.status) query += `&status=${opts.status}`;
if (opts.folder) query += `&folder=${opts.folder}`;
if (opts.limit) query += `&limit=${opts.limit}`;
@@ -291,12 +293,13 @@ export function emailCommand(): Command {
cmd
.command("set")
.description("Update email status")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.requiredOption("--email_id <id>", "Email ID")
.requiredOption("--status <status>", "New status (unread, read, archived)")
.option("--workspace <id>", "Workspace ID")
.action(async (opts, command) => {
- const { serverUrl, token, workspaceId } = resolveClientOpts(command, { workspace: opts.workspace, agentId: opts.agent_id });
+ const agentId = resolveAgentId(opts);
+ const { serverUrl, token, workspaceId } = resolveClientOpts(command, { workspace: opts.workspace, agentId });
const client = new APIClient(serverUrl, token, workspaceId);
if (!VALID_STATUSES.includes(opts.status)) {
@@ -320,7 +323,7 @@ export function emailCommand(): Command {
cmd
.command("send")
.description("Send an email from the agent")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.requiredOption("--to <addr>", "Recipient email address")
.requiredOption("--subject <s>", "Subject line")
.requiredOption("--body-file <path>", "Path to HTML body file")
@@ -334,9 +337,10 @@ export function emailCommand(): Command {
)
.option("--workspace <id>", "Workspace ID")
.action(async (opts, command) => {
+ const agentId = resolveAgentId(opts);
const { serverUrl, token, workspaceId } = resolveClientOpts(command, {
workspace: opts.workspace,
- agentId: opts.agent_id,
+ agentId,
});
const client = new APIClient(serverUrl, token, workspaceId);
@@ -409,7 +413,7 @@ export function emailCommand(): Command {
const traceId = process.env.ALOOK_TRACE_ID;
const sourceTaskId = process.env.ALOOK_TASK_ID;
const res = await client.postJSON<SendResponse>("/api/email/send", {
- agentId: opts.agent_id,
+ agentId,
to: opts.to,
subject: opts.subject,
htmlBody,
@@ -430,7 +434,7 @@ export function emailCommand(): Command {
cmd
.command("forward")
.description("Forward an email to a new recipient")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.requiredOption("--email_id <id>", "Source email ID to forward")
.requiredOption("--to <addr>", "Recipient email address")
.option("--from <addr>", "Send from a specific email address (custom mailbox)")
@@ -443,9 +447,10 @@ export function emailCommand(): Command {
)
.option("--workspace <id>", "Workspace ID")
.action(async (opts, command) => {
+ const agentId = resolveAgentId(opts);
const { serverUrl, token, workspaceId } = resolveClientOpts(command, {
workspace: opts.workspace,
- agentId: opts.agent_id,
+ agentId,
});
const client = new APIClient(serverUrl, token, workspaceId);
@@ -573,7 +578,7 @@ export function emailCommand(): Command {
const traceId = process.env.ALOOK_TRACE_ID;
const sourceTaskId = process.env.ALOOK_TASK_ID;
const res = await client.postJSON<SendResponse>("/api/email/send", {
- agentId: opts.agent_id,
+ agentId,
to: opts.to,
subject,
htmlBody,
@@ -599,19 +604,20 @@ export function emailCommand(): Command {
whitelistCmd
.command("list")
.description("List all whitelisted emails for an agent")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.option("--workspace <id>", "Workspace ID")
.option("--json", "Output as JSON")
.action(async (opts, command) => {
+ const agentId = resolveAgentId(opts);
const { serverUrl, token, workspaceId } = resolveClientOpts(command, {
workspace: opts.workspace,
- agentId: opts.agent_id,
+ agentId,
});
const client = new APIClient(serverUrl, token, workspaceId);
try {
const entries = await client.getJSON<WhitelistEntry[]>(
- `/api/agents/${opts.agent_id}/whitelist`,
+ `/api/agents/${agentId}/whitelist`,
);
if (!entries.length) {
@@ -637,19 +643,20 @@ export function emailCommand(): Command {
whitelistCmd
.command("add")
.description("Add an email to the whitelist")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.option("--workspace <id>", "Workspace ID")
.argument("<email>", "Email address to whitelist")
.action(async (email, opts, command) => {
+ const agentId = resolveAgentId(opts);
const { serverUrl, token, workspaceId } = resolveClientOpts(command, {
workspace: opts.workspace,
- agentId: opts.agent_id,
+ agentId,
});
const client = new APIClient(serverUrl, token, workspaceId);
try {
const entry = await client.postJSON<WhitelistEntry>(
- `/api/agents/${opts.agent_id}/whitelist`,
+ `/api/agents/${agentId}/whitelist`,
{ email: email.toLowerCase() },
);
console.log(`Added ${entry.email} to whitelist (id: ${entry.id})`);
@@ -667,20 +674,21 @@ export function emailCommand(): Command {
whitelistCmd
.command("delete")
.description("Remove an email from the whitelist")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.option("--workspace <id>", "Workspace ID")
.argument("<email>", "Email address to remove")
.action(async (email, opts, command) => {
+ const agentId = resolveAgentId(opts);
const { serverUrl, token, workspaceId } = resolveClientOpts(command, {
workspace: opts.workspace,
- agentId: opts.agent_id,
+ agentId,
});
const client = new APIClient(serverUrl, token, workspaceId);
const normalizedEmail = email.toLowerCase();
try {
const entries = await client.getJSON<WhitelistEntry[]>(
- `/api/agents/${opts.agent_id}/whitelist`,
+ `/api/agents/${agentId}/whitelist`,
);
const entry = entries.find((e) => e.email === normalizedEmail);
@@ -690,7 +698,7 @@ export function emailCommand(): Command {
}
await client.deleteJSON(
- `/api/agents/${opts.agent_id}/whitelist/${entry.id}`,
+ `/api/agents/${agentId}/whitelist/${entry.id}`,
);
console.log(`Removed ${normalizedEmail} from whitelist`);
} catch (err) {
diff --git a/src/cli/commands/issue.test.ts b/src/cli/commands/issue.test.ts
index be02baecb..12dfcfe6b 100644
--- a/src/cli/commands/issue.test.ts
+++ b/src/cli/commands/issue.test.ts
@@ -13,20 +13,20 @@ describe("issueCommand", () => {
expect(names).toContain("comment");
});
- it("create requires agent_id and title", () => {
+ it("create requires title; --agent_id is optional (env fallback)", () => {
const create = cmd.commands.find((c) => c.name() === "create")!;
const opts = (create as unknown as { options: { long: string; mandatory?: boolean }[] }).options;
const mandatory = opts.filter((o) => o.mandatory).map((o) => o.long);
- expect(mandatory).toContain("--agent_id");
+ expect(mandatory).not.toContain("--agent_id");
expect(mandatory).toContain("--title");
});
- it("show/update/comment require agent_id and issue_id", () => {
+ it("show/update/comment require issue_id; --agent_id is optional (env fallback)", () => {
for (const name of ["show", "update", "comment"]) {
const sub = cmd.commands.find((c) => c.name() === name)!;
const opts = (sub as unknown as { options: { long: string; mandatory?: boolean }[] }).options;
const mandatory = opts.filter((o) => o.mandatory).map((o) => o.long);
- expect(mandatory).toContain("--agent_id");
+ expect(mandatory).not.toContain("--agent_id");
expect(mandatory).toContain("--issue_id");
}
});
diff --git a/src/cli/commands/issue.ts b/src/cli/commands/issue.ts
index 43e8513f5..241259b4e 100644
--- a/src/cli/commands/issue.ts
+++ b/src/cli/commands/issue.ts
@@ -4,6 +4,7 @@ import { APIClient } from "../lib/client.js";
import { loadCLIConfigForProfile } from "../lib/config.js";
import { printJSON } from "../lib/output.js";
import { cmdPrefix } from "../lib/env.js";
+import { resolveAgentId } from "../lib/flags.js";
const VALID_STATUSES = ["todo", "in_progress", "review", "done", "closed", "canceled", "failed"];
@@ -99,18 +100,19 @@ export function issueCommand(): Command {
cmd
.command("create")
.description("Create and dispatch an issue to an agent")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.requiredOption("--title <title>", "Issue title")
.option("--description <text>", "Issue description")
.option("--body-file <path>", "Read issue description from a file")
.option("--json", "Output as JSON")
.action(async (opts, command) => {
- const { serverUrl, token, workspaceId } = resolveClientOpts(command, opts.agent_id);
+ const agentId = resolveAgentId(opts);
+ const { serverUrl, token, workspaceId } = resolveClientOpts(command, agentId);
const client = new APIClient(serverUrl, token, workspaceId);
const description = readBody({ body: opts.description, bodyFile: opts.bodyFile });
try {
const res = await client.postJSON<{ issue: IssueResponse }>("/api/issues", {
- agent_id: opts.agent_id,
+ agent_id: agentId,
title: opts.title,
description,
});
@@ -125,7 +127,7 @@ export function issueCommand(): Command {
cmd
.command("list")
.description("List issues for an agent")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.option("--status <status>", `Filter by status (${VALID_STATUSES.join(", ")})`)
.option("--completed", "Show completed/closed/canceled/failed issues")
.option("--all", "Show all issues")
@@ -135,9 +137,10 @@ export function issueCommand(): Command {
console.error(`Error: invalid status "${opts.status}"`);
process.exit(1);
}
- const { serverUrl, token, workspaceId } = resolveClientOpts(command, opts.agent_id);
+ const agentId = resolveAgentId(opts);
+ const { serverUrl, token, workspaceId } = resolveClientOpts(command, agentId);
const client = new APIClient(serverUrl, token, workspaceId);
- const params = new URLSearchParams({ agentId: opts.agent_id });
+ const params = new URLSearchParams({ agentId });
if (opts.status) params.set("status", opts.status);
if (!opts.all && !opts.status) params.set("terminal", opts.completed ? "true" : "false");
try {
@@ -157,16 +160,17 @@ export function issueCommand(): Command {
cmd
.command("show")
.description("Show issue details and conversation")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.requiredOption("--issue_id <id>", "Issue ID")
.option("--json", "Output as JSON")
.action(async (opts, command) => {
- const { serverUrl, token, workspaceId } = resolveClientOpts(command, opts.agent_id);
+ const agentId = resolveAgentId(opts);
+ const { serverUrl, token, workspaceId } = resolveClientOpts(command, agentId);
const client = new APIClient(serverUrl, token, workspaceId);
try {
- const res = await client.getJSON<{ issue: IssueResponse; messages: MessageResponse[]; comments: CommentResponse[] }>(`/api/issues/${opts.issue_id}?agentId=${encodeURIComponent(opts.agent_id)}`);
- if (res.issue.agent_id !== opts.agent_id) {
- console.error(`Error: issue ${res.issue.id} does not belong to agent ${opts.agent_id}`);
+ const res = await client.getJSON<{ issue: IssueResponse; messages: MessageResponse[]; comments: CommentResponse[] }>(`/api/issues/${opts.issue_id}?agentId=${encodeURIComponent(agentId)}`);
+ if (res.issue.agent_id !== agentId) {
+ console.error(`Error: issue ${res.issue.id} does not belong to agent ${agentId}`);
process.exit(1);
}
if (opts.json) return printJSON(res);
@@ -180,7 +184,7 @@ export function issueCommand(): Command {
cmd
.command("update")
.description("Update issue status or text")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.requiredOption("--issue_id <id>", "Issue ID")
.option("--status <status>", `New status (${VALID_STATUSES.join(", ")})`)
.option("--title <title>", "New title")
@@ -201,10 +205,11 @@ export function issueCommand(): Command {
console.error("Error: pass at least one of --status, --title, --description, --body-file");
process.exit(1);
}
- const { serverUrl, token, workspaceId } = resolveClientOpts(command, opts.agent_id);
+ const agentId = resolveAgentId(opts);
+ const { serverUrl, token, workspaceId } = resolveClientOpts(command, agentId);
const client = new APIClient(serverUrl, token, workspaceId);
try {
- const issue = await client.patchJSON<IssueResponse>(`/api/issues/${opts.issue_id}?agentId=${encodeURIComponent(opts.agent_id)}`, body);
+ const issue = await client.patchJSON<IssueResponse>(`/api/issues/${opts.issue_id}?agentId=${encodeURIComponent(agentId)}`, body);
if (opts.json) return printJSON(issue);
printIssue(issue);
} catch (err) {
@@ -216,7 +221,7 @@ export function issueCommand(): Command {
cmd
.command("comment")
.description("Append a comment to an issue")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.requiredOption("--issue_id <id>", "Issue ID")
.option("--body <text>", "Comment text")
.option("--body-file <path>", "Read comment from a file")
@@ -227,10 +232,11 @@ export function issueCommand(): Command {
console.error("Error: pass --body or --body-file");
process.exit(1);
}
- const { serverUrl, token, workspaceId } = resolveClientOpts(command, opts.agent_id);
+ const agentId = resolveAgentId(opts);
+ const { serverUrl, token, workspaceId } = resolveClientOpts(command, agentId);
const client = new APIClient(serverUrl, token, workspaceId);
try {
- const res = await client.postJSON<{ comment: CommentResponse }>(`/api/issues/${opts.issue_id}/comments?agentId=${encodeURIComponent(opts.agent_id)}`, { content });
+ const res = await client.postJSON<{ comment: CommentResponse }>(`/api/issues/${opts.issue_id}/comments?agentId=${encodeURIComponent(agentId)}`, { content });
if (opts.json) return printJSON(res);
console.log(`Commented on ${opts.issue_id}`);
} catch (err) {
diff --git a/src/cli/commands/sync.ts b/src/cli/commands/sync.ts
index a55256e71..ac6540ae0 100644
--- a/src/cli/commands/sync.ts
+++ b/src/cli/commands/sync.ts
@@ -5,6 +5,7 @@ import { APIClient } from "../lib/client.js";
import { loadCLIConfigForProfile } from "../lib/config.js";
import { printJSON } from "../lib/output.js";
import { cmdPrefix } from "../lib/env.js";
+import { resolveAgentId } from "../lib/flags.js";
const MIME_BY_EXT: Record<string, string> = {
".pdf": "application/pdf",
@@ -56,11 +57,12 @@ export function syncCommand(): Command {
cmd
.command("upload-artifact")
.description("Upload a file artifact to a conversation")
- .requiredOption("--agent_id <id>", "Agent ID")
+ .option("--agent_id <id>", "Agent ID")
.requiredOption("--conversation_id <id>", "Conversation ID")
.requiredOption("--file <path>", "Path to file to upload")
.action(async (opts, command) => {
- const { serverUrl, token, workspaceId } = resolveClientOpts(command, opts.agent_id);
+ const agentId = resolveAgentId(opts);
+ const { serverUrl, token, workspaceId } = resolveClientOpts(command, agentId);
const client = new APIClient(serverUrl, token, workspaceId);
let bytes: Buffer;
@@ -80,7 +82,7 @@ export function syncCommand(): Command {
new Blob([new Uint8Array(bytes)], { type: contentType }),
filename
);
- form.append("agent_id", opts.agent_id);
+ form.append("agent_id", agentId);
form.append("conversation_id", opts.conversation_id);
try {
diff --git a/src/cli/daemon/execenv/__tests__/context.test.ts b/src/cli/daemon/execenv/__tests__/context.test.ts
index 775e9b2d5..774d90649 100644
--- a/src/cli/daemon/execenv/__tests__/context.test.ts
+++ b/src/cli/daemon/execenv/__tests__/context.test.ts
@@ -1,4 +1,10 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+vi.mock("fs", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("fs")>();
+ return { ...actual, symlinkSync: vi.fn(actual.symlinkSync) };
+});
+
import {
mkdirSync,
writeFileSync,
@@ -8,6 +14,7 @@ import {
lstatSync,
readlinkSync,
symlinkSync,
+ unlinkSync,
} from "fs";
import { join } from "path";
import { tmpdir } from "os";
@@ -149,11 +156,13 @@ describe("ensureSymlinks", () => {
let workDir: string;
beforeEach(() => {
+ vi.mocked(symlinkSync).mockRestore();
workDir = join(tmpdir(), `execenv-test-${Date.now()}-${Math.random().toString(36).slice(2)}`);
mkdirSync(workDir, { recursive: true });
});
afterEach(() => {
+ vi.mocked(symlinkSync).mockRestore();
rmSync(workDir, { recursive: true, force: true });
});
@@ -206,6 +215,99 @@ describe("ensureSymlinks", () => {
expect(lstatSync(aliasPath).isSymbolicLink()).toBe(true);
expect(readlinkSync(aliasPath)).toBe(CANONICAL_FILE);
});
+
+ it("falls back to file copy when symlinkSync throws EPERM", () => {
+ writeFileSync(join(workDir, CANONICAL_FILE), "canonical content", "utf-8");
+ vi.mocked(symlinkSync).mockImplementation(() => {
+ const err = new Error("EPERM: operation not permitted, symlink") as NodeJS.ErrnoException;
+ err.code = "EPERM";
+ throw err;
+ });
+
+ ensureSymlinks(workDir);
+
+ const aliasPath = join(workDir, "CLAUDE.md");
+ expect(lstatSync(aliasPath).isFile()).toBe(true);
+ expect(lstatSync(aliasPath).isSymbolicLink()).toBe(false);
+ expect(readFileSync(aliasPath, "utf-8")).toBe("canonical content");
+ });
+
+ it("falls back to file copy when symlinkSync throws EACCES", () => {
+ writeFileSync(join(workDir, CANONICAL_FILE), "canonical content", "utf-8");
+ vi.mocked(symlinkSync).mockImplementation(() => {
+ const err = new Error("EACCES: permission denied, symlink") as NodeJS.ErrnoException;
+ err.code = "EACCES";
+ throw err;
+ });
+
+ ensureSymlinks(workDir);
+
+ const aliasPath = join(workDir, "CLAUDE.md");
+ expect(lstatSync(aliasPath).isFile()).toBe(true);
+ expect(readFileSync(aliasPath, "utf-8")).toBe("canonical content");
+ });
+
+ it("re-throws non-EPERM/EACCES errors from symlinkSync", () => {
+ writeFileSync(join(workDir, CANONICAL_FILE), "content", "utf-8");
+ vi.mocked(symlinkSync).mockImplementation(() => {
+ const err = new Error("EIO: i/o error, symlink") as NodeJS.ErrnoException;
+ err.code = "EIO";
+ throw err;
+ });
+
+ expect(() => ensureSymlinks(workDir)).toThrow("EIO");
+ });
+
+ it("existing regular file copy with matching content is left untouched", () => {
+ writeFileSync(join(workDir, CANONICAL_FILE), "same content", "utf-8");
+ writeFileSync(join(workDir, "CLAUDE.md"), "same content", "utf-8");
+ const mtimeBefore = lstatSync(join(workDir, "CLAUDE.md")).mtimeMs;
+
+ ensureSymlinks(workDir);
+
+ const aliasPath = join(workDir, "CLAUDE.md");
+ expect(lstatSync(aliasPath).isFile()).toBe(true);
+ expect(lstatSync(aliasPath).isSymbolicLink()).toBe(false);
+ expect(readFileSync(aliasPath, "utf-8")).toBe("same content");
+ expect(lstatSync(aliasPath).mtimeMs).toBe(mtimeBefore);
+ });
+
+ it("existing regular file copy with stale content is refreshed", () => {
+ writeFileSync(join(workDir, CANONICAL_FILE), "new content", "utf-8");
+ writeFileSync(join(workDir, "CLAUDE.md"), "old content", "utf-8");
+ vi.mocked(symlinkSync).mockImplementation(() => {
+ const err = new Error("EPERM: operation not permitted, symlink") as NodeJS.ErrnoException;
+ err.code = "EPERM";
+ throw err;
+ });
+
+ ensureSymlinks(workDir);
+
+ const aliasPath = join(workDir, "CLAUDE.md");
+ expect(readFileSync(aliasPath, "utf-8")).toBe("new content");
+ });
+
+ it("transitions from symlink to copy when permissions change", () => {
+ writeFileSync(join(workDir, CANONICAL_FILE), "content", "utf-8");
+ // First call creates a real symlink (symlinkSync uses real implementation by default)
+ ensureSymlinks(workDir);
+ expect(lstatSync(join(workDir, "CLAUDE.md")).isSymbolicLink()).toBe(true);
+
+ // Simulate permission loss — remove symlink and mock EPERM
+ unlinkSync(join(workDir, "CLAUDE.md"));
+ vi.mocked(symlinkSync).mockImplementation(() => {
+ const err = new Error("EPERM: operation not permitted, symlink") as NodeJS.ErrnoException;
+ err.code = "EPERM";
+ throw err;
+ });
+
+ ensureSymlinks(workDir);
+
+ const aliasPath = join(workDir, "CLAUDE.md");
+ expect(lstatSync(aliasPath).isFile()).toBe(true);
+ expect(lstatSync(aliasPath).isSymbolicLink()).toBe(false);
+ expect(readFileSync(aliasPath, "utf-8")).toBe("content");
+ });
});
describe("writeInstructionFileIfChanged", () => {
diff --git a/src/cli/daemon/execenv/context.test.ts b/src/cli/daemon/execenv/context.test.ts
index 028cd40f8..603346e8e 100644
--- a/src/cli/daemon/execenv/context.test.ts
+++ b/src/cli/daemon/execenv/context.test.ts
@@ -26,8 +26,10 @@ describe("buildInstructionContent email tool injection", () => {
});
const content = buildInstructionContent(task);
- expect(content).toContain("npx @alook/cli email pull --agent_id agent-123 --status unread");
- expect(content).toContain("npx @alook/cli email set --agent_id agent-123 --email_id <EMAIL_ID> --status read");
+ expect(content).toContain("npx @alook/cli email pull --status unread");
+ expect(content).toContain("npx @alook/cli email set --email_id <EMAIL_ID> --status read");
+ expect(content).not.toContain("email pull --agent_id");
+ expect(content).not.toContain("email set --agent_id");
expect(content).toContain(`${tempDir("alook-emails")}/ws1/agent-123/`);
expect(content).toContain("metadata.json");
expect(content).toContain("'[email protected]' (default, Alook platform address)");
@@ -39,7 +41,7 @@ describe("buildInstructionContent email tool injection", () => {
});
const content = buildInstructionContent(task);
- expect(content).toContain("npx @alook/cli email send --agent_id agent-123");
+ expect(content).toContain("npx @alook/cli email send --to");
expect(content).toContain("--body-file");
expect(content).toContain("--attachment");
});
@@ -61,7 +63,7 @@ describe("buildInstructionContent email tool injection", () => {
});
const content = buildInstructionContent(task);
- expect(content).not.toContain("email send --agent_id");
+ expect(content).not.toContain("email send --to");
});
it("includes owner email in opening line when user email is provided", () => {
@@ -112,14 +114,17 @@ describe("buildInstructionContent email tool injection", () => {
expect(content).not.toContain("## Email Tools");
});
- it("uses correct agent ID in email tool commands", () => {
+ it("does not include --agent_id in CLI examples and shows auto-detect note", () => {
const task = makeTask({
agentId: "specific-agent-id",
agent: { name: "test", instructions: "", emailHandle: "handle" },
});
const content = buildInstructionContent(task);
- expect(content).toContain("--agent_id specific-agent-id");
+ expect(content).not.toContain("--agent_id specific-agent-id");
+ expect(content).not.toContain("email pull --agent_id");
+ expect(content).not.toContain("calendar set --agent_id");
+ expect(content).toContain("The CLI auto-detects your identity from the environment");
});
it("still includes big boss instructions alongside email tools", () => {
diff --git a/src/cli/daemon/execenv/context.ts b/src/cli/daemon/execenv/context.ts
index 62e6c0d48..78fd744cb 100644
--- a/src/cli/daemon/execenv/context.ts
+++ b/src/cli/daemon/execenv/context.ts
@@ -10,6 +10,7 @@ import {
unlinkSync,
existsSync,
readlinkSync,
+ copyFileSync,
} from "fs";
import { join } from "path";
import type { Task } from "../types.js";
@@ -131,7 +132,7 @@ ${task.agent.instructions}
content += `\n## Alook CLI Tools
You can communicate with the world through Alook CLI.
-Your alook agent id is '${task.agentId}'. remember this, most of alook cli will requires you input your agent id.
+The CLI auto-detects your identity from the environment. No need to pass \`--agent_id\`.
`;
if (alookAddr || customAddrs.length > 0) {
@@ -142,12 +143,12 @@ Your alook agent id is '${task.agentId}'. remember this, most of alook cli will
### Emails
---
-Run '${cmdPrefix()} email pull --agent_id ${task.agentId} --status unread' to download unread emails from inbox to '${tempDir("alook-emails")}/${task.workspaceId}/${task.agentId}/'.
+Run '${cmdPrefix()} email pull --status unread' to download unread emails from inbox to '${tempDir("alook-emails")}/${task.workspaceId}/${task.agentId}/'.
---
-To download sent emails, add '--folder sent': '${cmdPrefix()} email pull --agent_id ${task.agentId} --folder sent'
+To download sent emails, add '--folder sent': '${cmdPrefix()} email pull --folder sent'
Valid folders: inbox (default), sent, untrust.
To limit the number of emails downloaded, add '--limit <N>' (e.g. '--limit 20'). Use '--offset <N>' to skip emails for pagination.
-Example: '${cmdPrefix()} email pull --agent_id ${task.agentId} --status unread --limit 20 --offset 0'
+Example: '${cmdPrefix()} email pull --status unread --limit 20 --offset 0'
---
Each email is saved to '${tempDir("alook-emails")}/${task.workspaceId}/${task.agentId}/<emailId>/' with:
- 'metadata.json' — sender, recipient, subject, date, status, message_id, in_reply_to, references
@@ -156,40 +157,40 @@ Each email is saved to '${tempDir("alook-emails")}/${task.workspaceId}/${task.ag
- 'attachments/' — extracted attachment files (if any)
---
Before starting to process an INBOX email, mark it as read:
-- Run '${cmdPrefix()} email set --agent_id ${task.agentId} --email_id <EMAIL_ID> --status read'
+- Run '${cmdPrefix()} email set --email_id <EMAIL_ID> --status read'
---
#### Sending a new email
Write the HTML body to a file first, then send it. The body is forwarded as-is (HTML).
-- Run '${cmdPrefix()} email send --agent_id ${task.agentId} --to <ADDRESS> --subject "<SUBJECT>" --body-file <PATH_TO_HTML>'
+- Run '${cmdPrefix()} email send --to <ADDRESS> --subject "<SUBJECT>" --body-file <PATH_TO_HTML>'
- To send from a specific mailbox, add '--from <YOUR_EMAIL_ADDRESS>'. Without '--from', the default Alook address is used.
- Attach files with '--attachment <PATH>' — repeat the flag for multiple attachments. Each file is uploaded before sending.
-- Example: '${cmdPrefix()} email send --agent_id ${task.agentId} --to [email protected] --subject "Weekly report" --body-file /tmp/body.html --from [email protected] --attachment /tmp/report.pdf'
+- Example: '${cmdPrefix()} email send --to [email protected] --subject "Weekly report" --body-file /tmp/body.html --from [email protected] --attachment /tmp/report.pdf'
#### Replying to an email
To reply to an email, add '--in-reply-to <EMAIL_ID>' to the send command. This sets the correct email threading headers so the recipient's email client groups the reply into the same conversation thread.
- Use 'Re: <original subject>' as the subject.
- Quote the original email body in your reply (wrap it in a blockquote).
- The <EMAIL_ID> is the Alook email id from metadata.json (not the message_id header).
-- Example: '${cmdPrefix()} email send --agent_id ${task.agentId} --to [email protected] --subject "Re: Bug report" --body-file /tmp/reply.html --in-reply-to <EMAIL_ID>'
+- Example: '${cmdPrefix()} email send --to [email protected] --subject "Re: Bug report" --body-file /tmp/reply.html --in-reply-to <EMAIL_ID>'
Tips:
- If you think the task will take a while, consider sending a short "I'm on it" style email reply first to reassure the sender.
---
#### Forwarding an email
Forward any email to a new recipient, with an optional note prepended above the original content. All original attachments are re-attached automatically.
-- Run '${cmdPrefix()} email forward --agent_id ${task.agentId} --email_id <EMAIL_ID> --to <RECIPIENT>'
+- Run '${cmdPrefix()} email forward --email_id <EMAIL_ID> --to <RECIPIENT>'
- Add '--note "FYI, see the request below."' to prepend a note above the forwarded body.
- Add '--from <YOUR_EMAIL_ADDRESS>' to send from a specific mailbox.
- Add '--attachment <PATH>' to attach extra files (repeatable).
-- Example: '${cmdPrefix()} email forward --agent_id ${task.agentId} --email_id em_abc --to [email protected] --note "FYI" --attachment /tmp/summary.pdf'
+- Example: '${cmdPrefix()} email forward --email_id em_abc --to [email protected] --note "FYI" --attachment /tmp/summary.pdf'
---
#### Email Whitelist (Allowed Senders)
Manage which email addresses are allowed to send you emails.
-- List: '${cmdPrefix()} email whitelist list --agent_id ${task.agentId}' (add '--json' for machine-readable output)
-- Add: '${cmdPrefix()} email whitelist add --agent_id ${task.agentId} <EMAIL_ADDRESS>'
-- Remove: '${cmdPrefix()} email whitelist delete --agent_id ${task.agentId} <EMAIL_ADDRESS>'
+- List: '${cmdPrefix()} email whitelist list' (add '--json' for machine-readable output)
+- Add: '${cmdPrefix()} email whitelist add <EMAIL_ADDRESS>'
+- Remove: '${cmdPrefix()} email whitelist delete <EMAIL_ADDRESS>'
---
`;
}
@@ -197,7 +198,7 @@ Manage which email addresses are allowed to send you emails.
content += `\n### Artifacts
Upload files for your owner to review in the app.
- Your current conversation id is available via env var: $ALOOK_CONVERSATION_ID
-- Run '${cmdPrefix()} sync upload-artifact --agent_id ${task.agentId} --conversation_id $ALOOK_CONVERSATION_ID --file <PATH>'
+- Run '${cmdPrefix()} sync upload-artifact --conversation_id $ALOOK_CONVERSATION_ID --file <PATH>'
- Use this after generating plans, reports, or any file the owner should review.
- You response will be rendered in remote server, so don't output link format with local path in your response (cause user can click it and jump to nowheres)
- If you think user may need to know any file detail, use upload-artifact tool to send the file to user.
@@ -219,26 +220,26 @@ Schedule future tasks for yourself. At the scheduled time, a new task is dispatc
Keep the event title informative and concise, less than 20 words.
Place the event details in description.
Create a one-off event:
-- Run '${cmdPrefix()} calendar set --agent_id ${task.agentId} --event_title "<TASK_TITLE>" --description "<TASK_BODY>" --datetime <YYYY-MM-DDTHH:MM>'
+- Run '${cmdPrefix()} calendar set --event_title "<TASK_TITLE>" --description "<TASK_BODY>" --datetime <YYYY-MM-DDTHH:MM>'
- '--datetime' is LOCAL time, format 'YYYY-MM-DDTHH:MM' (e.g. '2026-04-17T09:30'). Do NOT pass UTC / ISO strings with 'Z'.
- '--event_title' becomes the task prompt when the event fires — write it as the instruction you want future-you to receive.
Create a repeating event:
- Add '--repeat <interval>' where interval is like '1day', '2hour', '1week', '1month'.
- Optionally add '--repeat_stop_date <YYYY-MM-DD>' to stop the recurrence (local date).
-- Example: '${cmdPrefix()} calendar set --agent_id ${task.agentId} --event_title "<REPEAT_TASK_TITLE>" --description "<REPEAT_TASK_BODY>" --datetime 2026-04-18T09:00 --repeat 1day --repeat_stop_date 2026-05-18'
+- Example: '${cmdPrefix()} calendar set --event_title "<REPEAT_TASK_TITLE>" --description "<REPEAT_TASK_BODY>" --datetime 2026-04-18T09:00 --repeat 1day --repeat_stop_date 2026-05-18'
---
List upcoming events:
-- Run '${cmdPrefix()} calendar list --agent_id ${task.agentId}' (defaults: next 30 days, past 0 days).
+- Run '${cmdPrefix()} calendar list' (defaults: next 30 days, past 0 days).
- Tune the window with '--future_days <N>' and '--past_days <N>'. Add '--json' for machine-readable output.
- 'list' shows a '[has description]' badge instead of the full description — use 'show' (below) to read it.
Show full detail of one event (use this to read the description):
-- Run '${cmdPrefix()} calendar show --agent_id ${task.agentId} --event_id <EVENT_ID>'
+- Run '${cmdPrefix()} calendar show --event_id <EVENT_ID>'
- Add '--json' for machine-readable output.
Edit an existing event (preserves event id and recurring state):
-- Run '${cmdPrefix()} calendar update --agent_id ${task.agentId} --event_id <EVENT_ID> [flags]'
+- Run '${cmdPrefix()} calendar update --event_id <EVENT_ID> [flags]'
- Supply only the fields you want to change. Available flags:
- '--event_title "<t>"' — rename the event / change the fire-time prompt
- '--description "<d>"' to set, or '--clear_description' to remove
@@ -248,7 +249,7 @@ Edit an existing event (preserves event id and recurring state):
- Passing no mutating flag is an error. Do NOT use 'delete' + 'set' to edit — that loses the event id and the recurring 'last fired' state.
Delete an event:
-- Run '${cmdPrefix()} calendar delete --agent_id ${task.agentId} --event_id <EVENT_ID>'
+- Run '${cmdPrefix()} calendar delete --event_id <EVENT_ID>'
---
`;
@@ -288,7 +289,10 @@ export function ensureSymlinks(workDir: string): void {
if (target === CANONICAL_FILE) continue; // already correct
unlinkSync(aliasPath);
} else {
- // regular file — remove it
+ // regular file — check if content already matches (copy fallback fast-path)
+ const aliasContent = readFileSync(aliasPath, "utf-8");
+ const canonicalContent = readFileSync(canonicalPath, "utf-8");
+ if (aliasContent === canonicalContent) continue;
unlinkSync(aliasPath);
}
} catch (err: unknown) {
@@ -296,7 +300,16 @@ export function ensureSymlinks(workDir: string): void {
// doesn't exist — will create below
}
- symlinkSync(CANONICAL_FILE, aliasPath);
+ try {
+ symlinkSync(CANONICAL_FILE, aliasPath);
+ } catch (err: unknown) {
+ const code = (err as NodeJS.ErrnoException)?.code;
+ if (code === "EPERM" || code === "EACCES") {
+ copyFileSync(canonicalPath, aliasPath);
+ } else {
+ throw err;
+ }
+ }
}
}
diff --git a/src/cli/daemon/prompt.ts b/src/cli/daemon/prompt.ts
index 0df49d683..be41ca1ac 100644
--- a/src/cli/daemon/prompt.ts
+++ b/src/cli/daemon/prompt.ts
@@ -13,9 +13,9 @@ const EMAIL_NOTICE =
const ISSUE_NOTICE =
"This task was triggered by an assigned issue. The issue_id is provided in this message." +
- " Use `alook issue show --agent_id <your_agent_id> --issue_id <issue_id>` to read full context." +
- " Use `alook issue update --agent_id <your_agent_id> --issue_id <issue_id> --status <status>` to change status." +
- " Use `alook issue comment --agent_id <your_agent_id> --issue_id <issue_id> --body <text>` to leave a comment." +
+ " Use `alook issue show --issue_id <issue_id>` to read full context." +
+ " Use `alook issue update --issue_id <issue_id> --status <status>` to change status." +
+ " Use `alook issue comment --issue_id <issue_id> --body <text>` to leave a comment." +
" CRITICAL — You MUST manage the issue status correctly. This is NOT optional:" +
" 1. Set status to 'in_progress' when you start working." +
" 2. If you complete the work yourself: leave a summary comment, then set status to 'review' as your last action. 'review' means there is actual completed work (code, artifact, result) ready for the owner to look at." +
diff --git a/src/cli/lib/flags.test.ts b/src/cli/lib/flags.test.ts
index d28103308..534a6d275 100644
--- a/src/cli/lib/flags.test.ts
+++ b/src/cli/lib/flags.test.ts
@@ -1,5 +1,5 @@
-import { vi, describe, it, expect, afterEach } from "vitest";
-import { flagOrEnv } from "./flags.js";
+import { vi, describe, it, expect, afterEach, beforeEach } from "vitest";
+import { flagOrEnv, resolveAgentId } from "./flags.js";
function makeCmd(opts: Record<string, string>) {
return { opts: () => opts } as any;
@@ -40,3 +40,45 @@ describe("flagOrEnv", () => {
);
});
});
+
+describe("resolveAgentId", () => {
+ const originalEnv = process.env.ALOOK_AGENT_ID;
+
+ beforeEach(() => {
+ delete process.env.ALOOK_AGENT_ID;
+ });
+
+ afterEach(() => {
+ if (originalEnv !== undefined) {
+ process.env.ALOOK_AGENT_ID = originalEnv;
+ } else {
+ delete process.env.ALOOK_AGENT_ID;
+ }
+ });
+
+ it("returns flag value when both flag and env are set (flag wins)", () => {
+ process.env.ALOOK_AGENT_ID = "env_agent";
+ expect(resolveAgentId({ agent_id: "flag_agent" })).toBe("flag_agent");
+ });
+
+ it("returns env value when only env is set", () => {
+ process.env.ALOOK_AGENT_ID = "env_agent";
+ expect(resolveAgentId({})).toBe("env_agent");
+ });
+
+ it("calls process.exit(1) when neither is provided", () => {
+ const exitSpy = vi.spyOn(process, "exit").mockImplementation((() => {
+ throw new Error("__exit__");
+ }) as never);
+ const errSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+ expect(() => resolveAgentId({})).toThrow("__exit__");
+ expect(exitSpy).toHaveBeenCalledWith(1);
+ expect(errSpy).toHaveBeenCalledWith(
+ "Error: --agent_id is required (or set ALOOK_AGENT_ID env var)",
+ );
+
+ exitSpy.mockRestore();
+ errSpy.mockRestore();
+ });
+});
diff --git a/src/cli/lib/flags.ts b/src/cli/lib/flags.ts
index fb4f2238e..221418e9a 100644
--- a/src/cli/lib/flags.ts
+++ b/src/cli/lib/flags.ts
@@ -11,3 +11,12 @@ export function flagOrEnv(
if (process.env[envKey]) return process.env[envKey]!;
return fallback;
}
+
+export function resolveAgentId(opts: { agent_id?: string }): string {
+ const id = opts.agent_id || process.env.ALOOK_AGENT_ID;
+ if (!id) {
+ console.error("Error: --agent_id is required (or set ALOOK_AGENT_ID env var)");
+ process.exit(1);
+ }
+ return id;
+}