@saadnvd1/agent-os 0.3.807 → 0.3.815

package/lib/reach/types.ts

@@ -0,0 +1,96 @@
+/**
+ * Can other devices reach this machine, and if not, why. The facts are plain
+ * labels gathered from the machine (gatherFacts.ts); the classifier turns them
+ * into findings whose text comes from one table (classify.ts), so the CLI, the
+ * web app and the phone app all say the same thing.
+ */
+
+export type ReachRoute = "connect" | "tailscale" | "lan";
+
+export const REACH_CAUSES = [
+  "no-route",
+  "service-down",
+  "service-stuck",
+  "port-taken",
+  "lan-off",
+  "firewall",
+  "tailscale-missing",
+  "tailscale-logged-out",
+  "connect-not-linked",
+  "connect-off",
+  "connect-not-here",
+  "connect-denied",
+  "connector-not-ready",
+  "relay-down",
+  "origin-down",
+  "wrong-origin",
+  "dns",
+  "offline",
+  "certificate",
+] as const;
+
+export type ReachCause = (typeof REACH_CAUSES)[number];
+
+export type ReachStatus = "ok" | "warn" | "fail";
+
+export interface ReachFinding {
+  route?: ReachRoute;
+  status: ReachStatus;
+  cause?: ReachCause;
+  /** "nothing": AgentOS is retrying by itself; "you": the fix line is for you. */
+  needs: "you" | "nothing";
+  title: string;
+  /** One line: a command or what to do. Empty when nothing is needed. */
+  fix: string;
+  /** Its section of the reachability guide. */
+  guide?: string;
+  /** The link this route works on, when it works. */
+  url?: string;
+}
+
+export interface ReachReport {
+  status: ReachStatus;
+  /** The best link another device can use right now. */
+  url?: string;
+  findings: ReachFinding[];
+  checkedAt: string;
+}
+
+/** What answered when this machine fetched its own Connect address. */
+export type ConnectProbe =
+  | { kind: "ok" }
+  | { kind: "wrong-origin" }
+  // The edge's own error page: tunnel not connected, or origin unreachable.
+  | { kind: "edge"; status: number; tunnel: boolean }
+  | { kind: "dns"; scope: "host" | "all" }
+  | { kind: "tls"; skewed: boolean }
+  | { kind: "offline" }
+  | { kind: "timeout" };
+
+/** Why this server doesn't run Connect, as a label. */
+export type NotHere =
+  "env-off" | "dev-build" | "wrong-port" | "auth-off" | "lock" | "other";
+
+export interface ReachFacts {
+  now: number;
+  port: number;
+  lan: { on: boolean; addresses: string[] };
+  /** Read-only firewall reading: "blocks" only when it would stop LAN devices. */
+  firewall: "off" | "blocks" | "unknown";
+  tailscale: {
+    state: "running" | "logged-out" | "missing" | "unknown";
+    url?: string;
+  };
+  connect: {
+    state: "off" | "refused" | "error" | "connecting" | "up" | "denied";
+    linked: boolean;
+    enabled: boolean;
+    hostname?: string;
+    notHere?: NotHere;
+    /** Where the last failure came from: fetching the connector, or the service. */
+    stage?: "connector" | "service";
+    /** When the tunnel was last seen leaving "up" (or first trying). */
+    downSince?: number;
+  };
+  probe?: ConnectProbe;
+}

package/lib/security/auth.ts

@@ -95,6 +95,8 @@ const PUBLIC_EXACT = new Set([
   "/api/peer/hello",
   "/api/peer/hello/reveal",
   "/api/peer/hello/status",
+  // A constant per boot, so this machine can tell its own answer through Connect.
+  "/api/reach/probe",
   "/manifest.webmanifest",
   "/manifest.json",
   "/favicon.ico",

package/lib/security/demo.ts

@@ -146,6 +146,8 @@ const READS = [
   // stub: what a client checks before it trusts the server.
   "devices",
   "devices/network",
+  // A fixed "no way in" report: the demo never probes the internet.
+  "reach",
   // Whether this is a demo, for the UI.
   "demo",
   // The changelog: a static file, no agent.

package/lib/sessions/has-prompt.ts

@@ -0,0 +1,7 @@
+import type { Session } from "@/lib/db/types";
+
+// Whether a session is a task (it has a prompt). A list carries has_prompt
+// in place of the prompt's text; a single session carries the text.
+export const hasPrompt = (
+  s: Pick<Session, "task_prompt" | "has_prompt">
+): boolean => !!(s.has_prompt ?? s.task_prompt);

package/lib/sessions/omit-null.ts

@@ -0,0 +1,8 @@
+// A list row without its null fields: the client's types read a missing field
+// as null, and over half of a session row's columns are.
+export function omitNulls<T extends object>(row: T): T {
+  const out: Partial<T> = {};
+  for (const k of Object.keys(row) as (keyof T)[])
+    if (row[k] !== null) out[k] = row[k];
+  return out as T;
+}

package/lib/tasks/contract/views.ts

@@ -11,6 +11,17 @@ import type { TaskView } from "../index";
 import { viewOf } from "../move-targets";
 import * as client from "./client";
 
+// The list leaves out the fields that are null.
+const NULL_FIELDS = {
+  projectName: null,
+  branch: null,
+  baseBranch: null,
+  pr: null,
+  blocked: null,
+  cardUrl: null,
+  setup: null,
+} as const;
+
 function offlineView(
   session: Session,
   hostName: string,
@@ -68,6 +79,7 @@ async function viewsOn(hostId: string, rows: Session[]): Promise<TaskView[]> {
       }
       return [
         {
+          ...NULL_FIELDS,
           ...t,
           // As this machine mirrored it: the other one may predate views.
           view: viewOf(s),

package/lib/tasks/index.ts

@@ -67,6 +67,7 @@ import { saidSinceLastMessage } from "../chat/store";
 
 import { lastActiveOf } from "./last-active";
 import { setPlan, setTask } from "../db/session-parts";
+import { hasPrompt } from "../sessions/has-prompt";
 import { joinCrew } from "../sessions/crew";
 export * from "./state";
 export { codeReviewGate, codeReviewRefusal } from "./code-review";
@@ -77,7 +78,9 @@ export { assertMovable, moveTask } from "./move-flow";
 export interface TaskView {
   id: string;
   name: string;
-  prompt: string;
+  // A list leaves the text out (hasPrompt says there is one).
+  prompt?: string;
+  hasPrompt?: boolean;
   projectId: string | null;
   projectName: string | null;
   branch: string | null;
@@ -523,7 +526,8 @@ export async function taskView(session: Session): Promise<TaskView> {
   return {
     id: session.id,
     name: session.name,
-    prompt: session.task_prompt || "",
+    prompt: session.task_prompt || undefined,
+    hasPrompt: hasPrompt(session),
     projectId: session.project_id,
     projectName: project?.name ?? null,
     branch: session.branch_name,
@@ -563,9 +567,9 @@ export function movedTasks(): { id: string; movedTo: string | null }[] {
     .all() as { id: string; movedTo: string | null }[];
 }
 
-// Archived tasks aren't listed.
-export async function listTasks(): Promise<TaskView[]> {
-  const sessions = taskSessions(false);
+// Archived tasks aren't listed; mergedLimit keeps only the most recent merged.
+export async function listTasks(mergedLimit?: number): Promise<TaskView[]> {
+  const sessions = taskSessions(false, mergedLimit);
   const [local, remote] = await Promise.all([
     Promise.all(sessions.filter((s) => !isMirror(s)).map(taskView)),
     mirrorViews(sessions.filter(isMirror)),

package/lib/tasks/session.ts

@@ -31,12 +31,26 @@ import { setPr } from "../db/session-parts";
 export const expandHome = (p: string) => p.replace(/^~/, os.homedir());
 
 // Without the brief and system prompt: a list doesn't need them.
-export function taskSessions(includeArchived = true): Session[] {
+// mergedLimit keeps only that many of the most recently finished merged ones.
+export function taskSessions(
+  includeArchived = true,
+  mergedLimit?: number
+): Session[] {
+  const cap =
+    mergedLimit === undefined
+      ? ""
+      : `AND (task_status != 'merged' OR id IN (
+           SELECT id FROM session_rows
+             WHERE task_status = 'merged'
+               ${includeArchived ? "" : "AND archived_at IS NULL"}
+             ORDER BY COALESCE(NULLIF(merged_at, ''), updated_at) DESC
+             LIMIT ${Math.max(0, Math.floor(mergedLimit))}))`;
   return db
     .prepare(
       `SELECT ${sessionListColumns(db)} FROM session_rows
          WHERE task_status IS NOT NULL AND task_status != 'moved'
            ${includeArchived ? "" : "AND archived_at IS NULL"}
+           ${cap}
          ORDER BY created_at DESC`
     )
     .all() as Session[];

package/lib/tips/view.ts

@@ -3,6 +3,7 @@ import { tipApplies } from "./conditions";
 import { loadTips } from "./load";
 import { orderDeck, pickToday } from "./pick";
 import type { ClientTip, Tip, TipsView } from "./schema";
+import { guideUrl } from "@/lib/guides";
 import {
   readPinned,
   readSeen,
@@ -12,10 +13,7 @@ import {
   writeSeen,
 } from "./state";
 
-const GUIDES = "https://github.com/saadnvd1/agent-os/blob/main/docs/guides";
-
-export const guideUrl = (g: NonNullable<Tip["guide"]>) =>
-  `${GUIDES}/${g.file}.md${g.anchor ? `#${g.anchor}` : ""}`;
+export { guideUrl };
 
 const forClient = ({ id, title, body, guide, media }: Tip): ClientTip => ({
   id,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saadnvd1/agent-os",
-  "version": "0.3.807",
+  "version": "0.3.815",
   "description": "Self-hosted web UI for managing Claude Code sessions",
   "bin": {
     "agent-os": "scripts/agent-os"

package/scripts/agent-os

@@ -66,6 +66,7 @@ source "$SCRIPT_DIR/lib/prerequisites.sh"
 source "$SCRIPT_DIR/lib/ai-clis.sh"
 source "$SCRIPT_DIR/lib/commands.sh"
 source "$SCRIPT_DIR/lib/machine.sh"
+source "$SCRIPT_DIR/lib/setup.sh"
 
 # The package family the installers key off (debian, redhat, linux, macos),
 # and the WSL version (0 off WSL).
@@ -75,6 +76,8 @@ WSL=$(detect_wsl)
 # Main
 case "${1:-}" in
     install)          cmd_install "${2:-}" ;;
+    setup)            shift; cmd_setup "$@" ;;
+    check)            shift; aos_tsx lib/reach/cli.ts "$PORT" "$@" ;;
     start)            cmd_start ;;
     stop)             cmd_stop ;;
     restart)          cmd_restart ;;

package/scripts/install.sh

@@ -45,4 +45,15 @@ else
 fi
 
 # Run the install command
-exec "$INSTALL_DIR/scripts/agent-os" install
+"$INSTALL_DIR/scripts/agent-os" install
+
+# Under `curl | bash` stdin is this script, so ask on the terminal itself.
+if [[ -t 1 ]] && { : < /dev/tty; } 2> /dev/null; then
+    echo ""
+    read -p "Set up access from your phone and other devices now? [Y/n] " -r answer < /dev/tty || answer=n
+    if [[ ! "$answer" =~ ^[Nn] ]]; then
+        exec "$INSTALL_DIR/scripts/agent-os" setup < /dev/tty
+    fi
+fi
+echo ""
+echo "Next: agent-os setup"

package/scripts/lib/commands.sh

@@ -1,6 +1,9 @@
 #!/usr/bin/env bash
 # Command implementations for agent-os
 
+# The background service (launchd/systemd) the start/stop commands go through.
+source "${BASH_SOURCE[0]%/*}/service.sh"
+
 cmd_install() {
     local use_local=false
     [[ "${1:-}" == "--local" ]] && use_local=true
@@ -91,8 +94,8 @@ cmd_install() {
     fi
 
     echo "Next steps:"
-    echo "  agent-os start     Start the server"
-    echo "  agent-os enable    Auto-start on boot"
+    echo "  agent-os setup     Start it, keep it running, and reach it from your phone"
+    echo "  agent-os check     Can other devices reach this machine? (names the cause if not)"
     echo "  agent-os status    Show URLs"
     wsl_next_steps
 }
@@ -128,6 +131,16 @@ systemd_unit_active() {
 }
 
 cmd_start() {
+    if [[ "${OS:-}" == "macos" ]] && ! is_running && launchd_keeps_alive; then
+        if launchd_loaded; then
+            launchd_kickstart && log_success "AgentOS started (launchd)" && return 0
+        elif launchd_bootstrap; then
+            log_success "AgentOS started (launchd)"
+            return 0
+        fi
+        # No desktop session (ssh): run it by hand this time.
+        launchd_no_gui_session
+    fi
     if ! is_running && has_systemd &&
         systemctl --user is-enabled --quiet agent-os 2>/dev/null; then
         systemctl --user start agent-os
@@ -186,6 +199,15 @@ cmd_start() {
 }
 
 cmd_stop() {
+    # A kill would just be restarted: launchd stops it, until the next login
+    # or 'agent-os start'.
+    if [[ "${OS:-}" == "macos" ]] && launchd_loaded && launchd_keeps_alive; then
+        log_info "Stopping AgentOS (launchd)..."
+        launchd_bootout
+        rm -f "$PID_FILE"
+        log_success "AgentOS stopped"
+        return 0
+    fi
     if systemd_unit_active; then
         log_info "Stopping AgentOS (systemd)..."
         systemctl --user stop agent-os
@@ -226,6 +248,11 @@ cmd_stop() {
 }
 
 cmd_restart() {
+    if [[ "${OS:-}" == "macos" ]] && launchd_loaded && launchd_keeps_alive; then
+        launchd_restart
+        log_success "AgentOS restarted (launchd)"
+        return 0
+    fi
     if systemd_unit_active; then
         systemctl --user restart agent-os
         log_success "AgentOS restarted (systemd)"
@@ -387,69 +414,34 @@ cmd_enable() {
         exit 1
     fi
 
-    local script_path
-    script_path=$(realpath "$0")
-
     if [[ "$OS" == "macos" ]]; then
-        local plist_path="$HOME/Library/LaunchAgents/com.agent-os.plist"
-
-        cat > "$plist_path" << EOF
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-    <key>Label</key>
-    <string>com.agent-os</string>
-    <key>ProgramArguments</key>
-    <array>
-        <string>$script_path</string>
-        <string>start</string>
-    </array>
-    <key>RunAtLoad</key>
-    <true/>
-    <key>KeepAlive</key>
-    <false/>
-    <key>StandardOutPath</key>
-    <string>$LOG_FILE</string>
-    <key>StandardErrorPath</key>
-    <string>$LOG_FILE</string>
-    <key>EnvironmentVariables</key>
-    <dict>
-        <key>PATH</key>
-        <string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
-    </dict>
-</dict>
-</plist>
-EOF
-
-        launchctl load "$plist_path" 2>/dev/null || true
-        log_success "Auto-start enabled (launchd)"
-        echo "  Plist: $plist_path"
+        local result path managed=false
+        path=$(launchd_plist_path)
+        launchd_loaded && launchd_keeps_alive && managed=true
+        if [[ "$(service_file_state)" == same && "$managed" == true ]]; then
+            log_success "Auto-start already enabled (launchd)"
+            echo "  Plist: $path"
+            return 0
+        fi
+        # launchd runs the server itself from now on: one started by hand
+        # (or by the old plist) would hold the port it needs.
+        if is_running && [[ "$managed" == false ]]; then
+            cmd_stop
+        fi
+        result=$(service_reconcile)
+        [[ "$result" == updated ]] && log_info "Updated $path"
+        if launchd_bootstrap; then
+            log_success "Auto-start enabled (launchd): AgentOS starts at login and restarts after a crash"
+        else
+            launchd_no_gui_session
+        fi
+        echo "  Plist: $path"
 
     elif has_systemd; then
-        local service_dir="$HOME/.config/systemd/user"
-        local service_path="$service_dir/agent-os.service"
-
-        mkdir -p "$service_dir"
-
-        cat > "$service_path" << EOF
-[Unit]
-Description=AgentOS - AI Coding Session Manager
-After=network.target
-
-[Service]
-Type=simple
-ExecStart=$script_path start-foreground
-Restart=on-failure
-RestartSec=10
-# Only the server is stopped on a restart: terminals (tmux), chat workers and
-# an update in progress outlive it, as they do under launchd.
-KillMode=process
-Environment=PATH=/usr/local/bin:/usr/bin:/bin
-
-[Install]
-WantedBy=default.target
-EOF
+        local service_path
+        service_path=$(systemd_unit_path)
+        # Writes the unit only when it differs; the rest is safe to repeat.
+        service_reconcile > /dev/null
 
         systemctl --user daemon-reload
         systemctl --user enable agent-os
@@ -486,8 +478,8 @@ cmd_disable() {
         local plist_path="$HOME/Library/LaunchAgents/com.agent-os.plist"
 
         if [[ -f "$plist_path" ]]; then
-            launchctl unload "$plist_path" 2>/dev/null || true
-            rm -f "$plist_path"
+            launchd_bootout
+            rm -f "$plist_path" "$PID_FILE"
             log_success "Auto-start disabled"
         else
             log_warn "Auto-start was not enabled"
@@ -584,13 +576,15 @@ cmd_help() {
     echo ""
     echo "Commands:"
     echo "  install     Install AgentOS (auto-installs dependencies)"
+    echo "  setup       Guided setup: background service, how devices reach it, phone"
+    echo "  check       Can other devices reach this machine? Names the cause and the fix"
     echo "  run         Start server and open in browser"
     echo "  start       Start the server in background"
     echo "  stop        Stop the server"
     echo "  restart     Restart the server"
     echo "  status      Show server status and URLs"
     echo "  pair        Add a phone, tablet or laptop (prints a QR code)"
-    echo "  connect     Turn on AgentOS Connect for this machine (in development)"
+    echo "  connect     Turn on AgentOS Connect for this machine"
     echo "  disconnect  Turn Connect off; the tunnel closes within seconds"
     echo "  link        Link machines on your Connect account (link <name>, link accept <code>)"
     echo "  unlink      Unlink a machine linked through Connect"