@agentprojectcontext/apx 1.39.0 → 1.40.0

package/src/interfaces/web/src/components/routines/RoutineDetail.tsx

@@ -0,0 +1,86 @@
+import { Pencil, Play, Trash2, Zap } from "lucide-react";
+import type { RoutineEntry } from "../../lib/api";
+import { Badge, Button, Switch, Tip } from "../ui";
+import { cn } from "../../lib/cn";
+import { t } from "../../i18n";
+import { kindMeta, scheduleHuman } from "./shared";
+import { ReadOnlyBlock } from "./ReadOnlyBlock";
+import { ExecutionsList } from "./ExecutionsList";
+
+// Right column: read-only detail of the selected routine. Two stacked areas —
+// the data (header + meta + content blocks) takes the space it needs, and the
+// executions list below fills the rest and scrolls. Editing is behind a button.
+export function RoutineDetail({
+  pid, routine, onEdit, onRun, onToggle, onDelete, running,
+}: {
+  pid: string;
+  routine: RoutineEntry;
+  onEdit: () => void;
+  onRun: () => void;
+  onToggle: () => void;
+  onDelete: () => void;
+  running?: boolean;
+}) {
+  const meta = kindMeta()[routine.kind];
+  const Icon = meta?.icon || Zap;
+  const spec = (routine.spec || {}) as Record<string, any>;
+  const pre = routine.pre_commands || [];
+  const post = routine.post_commands || [];
+
+  // Read-only content blocks, in pipeline order (pre → action → post).
+  const blocks: { title: string; body: string; mono?: boolean }[] = [];
+  if (pre.length) blocks.push({ title: t("project.routines.block_pre"), body: pre.join("\n"), mono: true });
+  if (routine.kind === "exec_agent" || routine.kind === "super_agent") {
+    blocks.push({ title: t("project.routines.block_prompt"), body: String(spec.prompt || "") });
+  } else if (routine.kind === "telegram") {
+    blocks.push({ title: t("project.routines.block_text"), body: String(spec.text || "") });
+  } else if (routine.kind === "shell") {
+    blocks.push({ title: t("project.routines.block_command"), body: String(spec.command || ""), mono: true });
+  } else if (routine.kind === "heartbeat") {
+    blocks.push({ title: t("project.routines.block_text"), body: String(spec.message || "") });
+  }
+  if (post.length) blocks.push({ title: t("project.routines.block_post"), body: post.join("\n"), mono: true });
+
+  return (
+    <div className="flex h-full min-h-0 flex-col">
+      {/* DATA — takes the space it needs; scrolls only if it overflows */}
+      <div className="min-h-0 shrink space-y-4 overflow-y-auto p-4">
+        {/* header: name + actions (edit behind a button) */}
+        <div className="flex items-start justify-between gap-3">
+          <div className="flex min-w-0 items-center gap-2">
+            <span className={cn("flex size-7 shrink-0 items-center justify-center rounded-lg", routine.enabled ? "bg-emerald-500/15 text-emerald-400" : "bg-muted text-muted-fg")}>
+              <Icon size={14} />
+            </span>
+            <h3 className="truncate text-base font-semibold">{routine.name}</h3>
+            <Badge tone={routine.kind === "shell" ? "warning" : "info"}>{meta?.label || routine.kind}</Badge>
+          </div>
+          <div className="flex shrink-0 items-center gap-2">
+            <Switch checked={routine.enabled} onChange={onToggle} />
+            <Tip content={t("common.run")}><Button size="sm" variant="secondary" onClick={onRun} loading={running}><Play size={13} /></Button></Tip>
+            <Tip content={t("project.routines.edit_hint")}><Button size="sm" variant="secondary" onClick={onEdit}><Pencil size={13} /> {t("project.routines.edit_btn")}</Button></Tip>
+            <Tip content={t("common.delete")}><Button size="sm" variant="destructive" onClick={onDelete}><Trash2 size={13} /></Button></Tip>
+          </div>
+        </div>
+
+        {/* compact meta: schedule / next / last */}
+        <div className="flex flex-wrap items-center gap-x-4 gap-y-1 text-xs text-muted-fg">
+          <span>⏱ {scheduleHuman(routine.schedule)}</span>
+          {routine.next_run_at && <span>{t("project.routines.next_run")} {new Date(routine.next_run_at).toLocaleString()}</span>}
+          {routine.last_run_at && <span>{t("project.routines.last_run")} {new Date(routine.last_run_at).toLocaleString()}</span>}
+          <span className={cn(routine.last_status === "ok" && "text-emerald-500", routine.last_status === "error" && "text-destructive")}>
+            {t("agents_ui.last_label")} {routine.last_status || "—"}
+          </span>
+        </div>
+        {routine.last_error && <div className="rounded-md bg-destructive/10 px-2 py-1 text-xs text-destructive">{routine.last_error}</div>}
+
+        {/* read-only content blocks */}
+        <div className="space-y-3">
+          {blocks.map((b) => <ReadOnlyBlock key={b.title} title={b.title} body={b.body} mono={b.mono} />)}
+        </div>
+      </div>
+
+      {/* EXECUTIONS — fills the remaining height and scrolls */}
+      <ExecutionsList pid={pid} name={routine.name} running={running} />
+    </div>
+  );
+}

package/src/interfaces/web/src/components/routines/RoutineEditor.tsx

@@ -0,0 +1,263 @@
+import { useEffect, useState } from "react";
+import useSWR from "swr";
+import { ArrowRight, Terminal } from "lucide-react";
+import { Routines, Agents, Telegram, type RoutineEntry } from "../../lib/api";
+import { Button, Dialog, Field, Input, Switch } from "../ui";
+import { UiSelect } from "../UiSelect";
+import { useToast } from "../Toast";
+import { cn } from "../../lib/cn";
+import { t } from "../../i18n";
+import { type Kind, kindMeta, kindOptions, schedPresets, scheduleHuman, splitLines, varsFor } from "./shared";
+import { VarTextarea } from "./VarTextarea";
+import { AvailableVarsCard } from "./AvailableVarsCard";
+
+export function RoutineEditor({
+  draft, onClose, onSaved, pid,
+}: { draft: Partial<RoutineEntry> | null; onClose: () => void; onSaved: () => void; pid: string }) {
+  const toast = useToast();
+  const agentsList = useSWR(draft ? `/projects/${pid}/agents` : null, () => Agents.list(pid));
+  const [busy, setBusy] = useState(false);
+
+  const [name, setName] = useState("");
+  const [kind, setKind] = useState<Kind>("super_agent");
+  const [schedule, setSchedule] = useState("every:10m");
+  const [enabled, setEnabled] = useState(true);
+  // Per-kind fields
+  const [agent, setAgent] = useState("");
+  const [prompt, setPrompt] = useState("");
+  const [tgChannel, setTgChannel] = useState("default");
+  const [tgChatId, setTgChatId] = useState("");
+  const [tgText, setTgText] = useState("");
+  const [command, setCommand] = useState("");
+  const [hbChannel, setHbChannel] = useState("heartbeat");
+  const [hbMessage, setHbMessage] = useState("");
+  const [pre, setPre] = useState("");
+  const [post, setPost] = useState("");
+
+  // Telegram channels for the selector (default + any project/global channels).
+  const tgChannels = useSWR(draft && kind === "telegram" ? "/telegram/channels" : null, () => Telegram.channels.list());
+
+  // Load draft → fields.
+  useEffect(() => {
+    if (!draft) return;
+    const spec = (draft.spec && typeof draft.spec === "object" ? draft.spec : {}) as Record<string, any>;
+    setName(draft.name || "");
+    setKind((draft.kind as Kind) || "super_agent");
+    setSchedule(draft.schedule || "every:10m");
+    setEnabled(draft.enabled ?? true);
+    setAgent(spec.agent || "");
+    setPrompt(spec.prompt || "");
+    setTgChannel(spec.channel || "default");
+    setTgChatId(spec.chat_id ? String(spec.chat_id) : "");
+    setTgText(spec.text || "");
+    setCommand(spec.command || "");
+    setHbChannel(spec.channel || "heartbeat");
+    setHbMessage(spec.message || "");
+    setPre((draft.pre_commands || []).join("\n"));
+    setPost((draft.post_commands || []).join("\n"));
+  }, [draft]);
+
+  // Pre/post shell wrap the LLM kinds AND telegram (pre can fetch data, the text
+  // can use {{pre_output}}, post can react to the result).
+  const usesPrePost = kind === "exec_agent" || kind === "super_agent" || kind === "telegram";
+
+  const buildSpec = (): Record<string, unknown> => {
+    switch (kind) {
+      case "exec_agent": return { agent, prompt };
+      case "super_agent": return { prompt };
+      case "telegram": return { channel: tgChannel, ...(tgChatId ? { chat_id: tgChatId } : {}), text: tgText };
+      case "shell": return { command };
+      case "heartbeat": return { channel: hbChannel, message: hbMessage };
+    }
+  };
+
+  const submit = async () => {
+    if (!name) { toast.error(t("project.routines.name_required")); return; }
+    setBusy(true);
+    try {
+      await Routines.upsert(pid, {
+        name, kind, schedule, enabled,
+        spec: buildSpec(),
+        pre_commands: usesPrePost ? splitLines(pre) : [],
+        post_commands: usesPrePost ? splitLines(post) : [],
+      });
+      toast.success(t("project.routines.saved"));
+      onSaved();
+    } catch (e: any) { toast.error(e?.message || t("project.routines.save_error")); }
+    finally { setBusy(false); }
+  };
+
+  // Channel options: "default" + configured channels + the current value.
+  const channelOptions = (() => {
+    const list = tgChannels.data?.channels || [];
+    const names = ["default", ...list.map((c) => c.name)];
+    if (tgChannel && !names.includes(tgChannel)) names.push(tgChannel);
+    const seen = new Set<string>();
+    return names
+      .filter((n) => (seen.has(n) ? false : (seen.add(n), true)))
+      .map((n) => {
+        const ch = list.find((c) => c.name === n);
+        const description = ch?.project ? `proyecto ${ch.project}` : ch?.chat_id ? `chat ${ch.chat_id}` : undefined;
+        return { value: n, label: n, description };
+      });
+  })();
+
+  // Timeline steps (pre → action → post).
+  const preSteps = usesPrePost ? splitLines(pre) : [];
+  const postSteps = usesPrePost ? splitLines(post) : [];
+  const actionLabel = (() => {
+    switch (kind) {
+      case "exec_agent": return agent ? t("agents_ui.action_agent_answers", { agent }) : t("agents_ui.action_agent_pick_answers");
+      case "super_agent": return t("agents_ui.action_super_answers");
+      case "telegram": return t("agents_ui.action_telegram_channel", { channel: tgChannel });
+      case "shell": return command ? t("agents_ui.summary_runs_cmd", { cmd: command.slice(0, 48) }) : t("agents_ui.action_runs_shell");
+      case "heartbeat": return t("agents_ui.summary_heartbeat");
+    }
+  })();
+  const actionDetail =
+    kind === "telegram" ? tgText :
+    kind === "shell" ? command :
+    kind === "heartbeat" ? hbMessage :
+    prompt;
+
+  const ActionIcon = kindMeta()[kind].icon;
+  const steps = [
+    ...preSteps.map((c, i) => ({ id: `pre-${i}`, icon: Terminal, label: t("agents_ui.step_pre"), detail: c, action: false })),
+    { id: "action", icon: ActionIcon, label: actionLabel, detail: actionDetail ? actionDetail.slice(0, 90) : t("project.routines.block_empty"), action: true },
+    ...postSteps.map((c, i) => ({ id: `post-${i}`, icon: Terminal, label: t("agents_ui.step_post"), detail: c, action: false })),
+  ];
+
+  return (
+    <Dialog
+      open={!!draft}
+      onClose={onClose}
+      title={draft?.name ? t("project.routines.edit_title", { name: draft.name }) : t("project.routines.new_title")}
+      description={t("project.routines.dialog_desc")}
+      size="xl"
+      footer={
+        <>
+          <Button variant="ghost" onClick={onClose} disabled={busy}>{t("common.cancel")}</Button>
+          <Button variant="primary" onClick={submit} loading={busy}>{t("common.save")}</Button>
+        </>
+      }
+    >
+      <div className="space-y-4">
+        <div className="grid gap-6 md:grid-cols-2">
+          {/* LEFT — opciones + enabled + variables disponibles */}
+          <div className="space-y-3">
+            <div className="flex items-center justify-between rounded-lg border border-border bg-muted/20 px-3 py-2">
+              <Switch checked={enabled} onChange={setEnabled} label={t("project.routines.enabled_label")} />
+              <span className="text-[11px] text-muted-fg">{enabled ? t("project.routines.enabled_hint") : t("project.routines.disabled_hint")}</span>
+            </div>
+            <Field label={t("project.routines.name_field")} hint={draft?.name ? t("project.routines.name_no_edit") : undefined}>
+              <Input value={name} disabled={!!draft?.name} onChange={(e) => setName(e.target.value)} placeholder="resumen-diario" />
+            </Field>
+            <Field label={t("project.routines.kind_field")}>
+              <UiSelect value={kind} onChange={(v) => setKind(v as Kind)} options={kindOptions(kind)} />
+            </Field>
+            <p className="-mt-1 text-[11px] text-muted-fg">{kindMeta()[kind].desc}</p>
+            {kind === "exec_agent" && (
+              <Field label={t("project.routines.agent_field")} hint={t("project.routines.agent_hint")}>
+                <UiSelect value={agent} onChange={setAgent} placeholder={agentsList.isLoading ? t("project.routines.agent_loading") : t("project.routines.agent_pick")}
+                  options={(agentsList.data || []).map((a) => ({ value: a.slug, label: a.slug, description: [a.role, a.model].filter(Boolean).join(" · ") || undefined }))} />
+              </Field>
+            )}
+            <Field label={t("project.routines.schedule_field")} hint={t("project.routines.schedule_hint")}>
+              <div className="space-y-2">
+                <div className="flex flex-wrap gap-1">
+                  {schedPresets().map((s) => (
+                    <button key={s.value} type="button" onClick={() => setSchedule(s.value)}
+                      className={cn("rounded-md border px-2 py-0.5 text-[11px]", schedule === s.value ? "border-emerald-500/50 text-emerald-400" : "border-border text-muted-fg hover:text-foreground")}>
+                      {s.label}
+                    </button>
+                  ))}
+                  <button type="button" onClick={() => setSchedule("manual")}
+                    className={cn("rounded-md border px-2 py-0.5 text-[11px]", schedule === "manual" ? "border-emerald-500/50 text-emerald-400" : "border-border text-muted-fg hover:text-foreground")}>
+                    {t("agents_ui.preset_manual")}
+                  </button>
+                </div>
+                <Input value={schedule} onChange={(e) => setSchedule(e.target.value)} placeholder="every:10m · cron 0 9 * * 1-5 · once:ISO · manual" />
+              </div>
+            </Field>
+            <AvailableVarsCard />
+          </div>
+
+          {/* RIGHT — lo que ejecuta, según el tipo. Cada textarea trae sus
+              variables como chips clickeables debajo. */}
+          <div className="space-y-3">
+            {/* pre → action → post (las variables aparecen donde se usan) */}
+            {usesPrePost && (
+              <VarTextarea
+                label={t("project.routines.pre_field")} hint={t("project.routines.pre_hint")}
+                rows={2} mono value={pre} onChange={setPre} vars={varsFor("pre")}
+                placeholder="curl -s https://wttr.in/Bariloche"
+              />
+            )}
+            {kind === "exec_agent" && (
+              <VarTextarea label={t("project.routines.prompt_exec")} rows={4} value={prompt} onChange={setPrompt}
+                vars={varsFor("prompt")} placeholder={t("project.routines.prompt_exec_ph")} />
+            )}
+            {kind === "super_agent" && (
+              <VarTextarea label={t("project.routines.prompt_super")} rows={4} value={prompt} onChange={setPrompt}
+                vars={varsFor("prompt")} placeholder={t("project.routines.prompt_super_ph")} />
+            )}
+
+            {/* Telegram: channel selector + chat id + texto (con {{pre_output}}) */}
+            {kind === "telegram" && (
+              <>
+                <div className="grid grid-cols-2 gap-3">
+                  <Field label={t("project.routines.tg_channel")}>
+                    <UiSelect value={tgChannel} onChange={setTgChannel} options={channelOptions} />
+                  </Field>
+                  <Field label={t("project.routines.tg_chat_id")}><Input value={tgChatId} onChange={(e) => setTgChatId(e.target.value)} placeholder={t("agents_ui.tg_chat_id_ph")} /></Field>
+                </div>
+                <VarTextarea label={t("project.routines.tg_text")} hint={t("project.routines.tg_text_hint")}
+                  rows={6} value={tgText} onChange={setTgText} vars={varsFor("prompt")} placeholder={t("agents_ui.tg_text_ph")} />
+              </>
+            )}
+
+            {/* Shell: un comando, sin variables */}
+            {kind === "shell" && (
+              <VarTextarea label={t("project.routines.shell_field")} hint={t("project.routines.shell_hint")}
+                rows={11} mono value={command} onChange={setCommand} vars={[]} placeholder="cd /repo && git pull && npm test" />
+            )}
+
+            {/* Heartbeat: solo loguea (no se ofrece para rutinas nuevas) */}
+            {kind === "heartbeat" && (
+              <div className="grid grid-cols-2 gap-3">
+                <Field label={t("project.routines.hb_channel")}><Input value={hbChannel} onChange={(e) => setHbChannel(e.target.value)} placeholder="heartbeat" /></Field>
+                <Field label={t("project.routines.hb_message")}><Input value={hbMessage} onChange={(e) => setHbMessage(e.target.value)} placeholder={t("agents_ui.hb_message_ph")} /></Field>
+              </div>
+            )}
+
+            {usesPrePost && (
+              <VarTextarea
+                label={t("project.routines.post_field")} hint={t("project.routines.post_hint")}
+                rows={2} mono value={post} onChange={setPost} vars={varsFor("post")}
+                placeholder={'apx telegram send "$APX_LLM_OUTPUT"'}
+              />
+            )}
+          </div>
+        </div>
+
+        {/* Qué va a pasar — full width */}
+        <div className="rounded-lg border border-border bg-muted/20 p-3">
+          <div className="mb-2 text-xs font-semibold text-muted-fg">{t("project.routines.what_happens")} <span className="font-normal text-muted-fg">· ⏱ {scheduleHuman(schedule)}</span></div>
+          <div className="flex flex-wrap items-stretch gap-2">
+            {steps.map((s, i) => (
+              <div key={s.id} className="flex items-stretch gap-2">
+                <div className={cn("flex max-w-[240px] flex-col gap-1 rounded-lg border px-2.5 py-2", s.action ? "border-emerald-500/40 bg-emerald-500/5" : "border-border bg-card")}>
+                  <div className={cn("flex items-center gap-1.5 text-[11px] font-medium", s.action ? "text-emerald-400" : "text-muted-fg")}>
+                    <s.icon size={12} /> {s.label}
+                  </div>
+                  {s.detail && <div className="line-clamp-2 font-mono text-[10px] text-muted-fg">{s.detail}</div>}
+                </div>
+                {i < steps.length - 1 && <ArrowRight size={14} className="shrink-0 self-center text-muted-fg" />}
+              </div>
+            ))}
+          </div>
+        </div>
+      </div>
+    </Dialog>
+  );
+}

package/src/interfaces/web/src/components/routines/RoutineList.tsx

@@ -0,0 +1,59 @@
+import { Zap } from "lucide-react";
+import type { RoutineEntry } from "../../lib/api";
+import { StatusDot } from "../Section";
+import { cn } from "../../lib/cn";
+import { t } from "../../i18n";
+import { kindMeta, scheduleHuman } from "./shared";
+
+// Left column: scrollable list of routines. Click selects (the divider is the
+// single border-r line); the detail lives in the sibling column.
+export function RoutineList({
+  routines, selectedName, onSelect,
+}: {
+  routines: RoutineEntry[];
+  selectedName: string | null;
+  onSelect: (name: string) => void;
+}) {
+  return (
+    <aside className="flex h-full min-h-0 flex-col border-r border-border">
+      <div className="shrink-0 px-3 py-2.5 text-[11px] font-semibold uppercase tracking-wide text-muted-fg">
+        {t("project.routines.list_title")}
+      </div>
+      <ul className="min-h-0 flex-1 space-y-1 overflow-y-auto p-2 pt-0">
+        {routines.map((r) => {
+          const meta = kindMeta()[r.kind];
+          const Icon = meta?.icon || Zap;
+          const active = r.name === selectedName;
+          return (
+            <li key={r.name}>
+              <button
+                type="button"
+                onClick={() => onSelect(r.name)}
+                aria-current={active}
+                className={cn(
+                  "w-full rounded-lg border px-2.5 py-2 text-left transition-colors",
+                  active
+                    ? "border-primary/50 bg-primary/10"
+                    : "border-transparent hover:border-border hover:bg-accent/40",
+                )}
+              >
+                <div className="flex items-center gap-2">
+                  <span className={cn("flex size-6 shrink-0 items-center justify-center rounded-md", r.enabled ? "bg-emerald-500/15 text-emerald-400" : "bg-muted text-muted-fg")}>
+                    <Icon size={13} />
+                  </span>
+                  <span className="min-w-0 flex-1 truncate text-sm font-medium">{r.name}</span>
+                  {!r.enabled && <span className="shrink-0 text-[10px] text-muted-fg">{t("project.routines.paused")}</span>}
+                  <StatusDot ok={r.last_status === "ok" ? true : r.last_status === "error" ? false : null} />
+                </div>
+                <div className="mt-1 flex items-center justify-between gap-2 pl-8 text-[10px] text-muted-fg">
+                  <span className="truncate">{meta?.label || r.kind}</span>
+                  <span className="shrink-0">⏱ {scheduleHuman(r.schedule)}</span>
+                </div>
+              </button>
+            </li>
+          );
+        })}
+      </ul>
+    </aside>
+  );
+}

package/src/interfaces/web/src/components/routines/VarTextarea.tsx

@@ -0,0 +1,70 @@
+import { useRef } from "react";
+import { Textarea } from "../ui";
+import { cn } from "../../lib/cn";
+
+type Var = { v: string };
+
+// A labelled textarea with its context's variables as click-to-insert chips
+// underneath. The chips have NO tooltip (the explanations live in the
+// "available variables" reference card); clicking one drops the token at the
+// caret (or appends it). Label is a <div> (not <label>) so the chip buttons
+// don't collide with native label→control focusing. The hint sits under the
+// title, above the textarea.
+export function VarTextarea({
+  label, hint, value, onChange, vars, rows = 3, mono, placeholder,
+}: {
+  label: string;
+  hint?: string;
+  value: string;
+  onChange: (v: string) => void;
+  vars: Var[];
+  rows?: number;
+  mono?: boolean;
+  placeholder?: string;
+}) {
+  const wrapRef = useRef<HTMLDivElement>(null);
+
+  const insert = (token: string) => {
+    const ta = wrapRef.current?.querySelector("textarea");
+    if (!ta) { onChange(value ? `${value}${token}` : token); return; }
+    const start = ta.selectionStart ?? value.length;
+    const end = ta.selectionEnd ?? value.length;
+    const next = value.slice(0, start) + token + value.slice(end);
+    onChange(next);
+    requestAnimationFrame(() => {
+      ta.focus();
+      const pos = start + token.length;
+      ta.setSelectionRange(pos, pos);
+    });
+  };
+
+  return (
+    <div className="space-y-1">
+      <div className="text-xs font-medium text-muted-foreground">{label}</div>
+      {hint && <div className="text-[11px] text-muted-foreground/70">{hint}</div>}
+      <div ref={wrapRef} className="space-y-1.5">
+        <Textarea
+          rows={rows}
+          className={cn(mono && "font-mono text-xs")}
+          value={value}
+          onChange={(e) => onChange(e.target.value)}
+          placeholder={placeholder}
+        />
+        {vars.length > 0 && (
+          <div className="flex flex-wrap gap-1">
+            {vars.map((v) => (
+              <button
+                key={v.v}
+                type="button"
+                onClick={() => insert(v.v)}
+                className="inline-flex items-center rounded-md border border-border bg-card px-1.5 py-0.5 font-mono text-[10px] text-muted-fg transition-colors hover:border-muted-fg/50 hover:text-foreground"
+              >
+                {v.v}
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/interfaces/web/src/components/routines/shared.ts

@@ -0,0 +1,89 @@
+// Shared helpers for the Routines screen + its components.
+// Kept framework-free (pure functions + i18n) so list/detail/editor reuse them.
+import { Bot, Crown, Heart, Send, Terminal } from "lucide-react";
+import type { RoutineEntry } from "../../lib/api";
+import { t } from "../../i18n";
+
+export type Kind = RoutineEntry["kind"];
+
+export function splitLines(v: string): string[] {
+  return v.split("\n").map((s) => s.trim()).filter(Boolean);
+}
+
+// Friendly action types (maps to routines.js kinds).
+export function kindMeta(): Record<Kind, { label: string; desc: string; icon: typeof Bot }> {
+  return {
+    exec_agent:  { label: t("agents_ui.kind_exec_agent"),  desc: t("agents_ui.kind_exec_agent_desc"), icon: Bot },
+    super_agent: { label: t("agents_ui.kind_super_agent"), desc: t("agents_ui.kind_super_agent_desc"), icon: Crown },
+    telegram:    { label: t("agents_ui.kind_telegram"),    desc: t("agents_ui.kind_telegram_desc"), icon: Send },
+    shell:       { label: t("agents_ui.kind_shell"),       desc: t("agents_ui.kind_shell_desc"), icon: Terminal },
+    heartbeat:   { label: t("agents_ui.kind_heartbeat"),   desc: t("agents_ui.kind_heartbeat_desc"), icon: Heart },
+  };
+}
+
+export function kindOptions(includeKind?: Kind) {
+  const meta = kindMeta();
+  // Heartbeat is no longer offered for new routines (the runner already logs a
+  // per-run line — see AGENTS.md). Keep it only when editing an existing one.
+  return (Object.keys(meta) as Kind[])
+    .filter((k) => k !== "heartbeat" || includeKind === "heartbeat")
+    .map((k) => ({ value: k, label: meta[k].label, description: meta[k].desc, icon: meta[k].icon }));
+}
+
+// "every:10m" → "cada 10 minutos", cron/once → legible.
+export function scheduleHuman(s?: string): string {
+  if (!s) return "—";
+  if (s.startsWith("every:")) {
+    const v = s.slice(6);
+    const m = v.match(/^(\d+)(s|m|h|d)$/);
+    if (m) {
+      const n = m[1];
+      const unit = {
+        s: t("agents_ui.unit_seconds"),
+        m: t("agents_ui.unit_minutes"),
+        h: t("agents_ui.unit_hours"),
+        d: t("agents_ui.unit_days"),
+      }[m[2]] || m[2];
+      return t("agents_ui.every_n_unit", { n, unit });
+    }
+    return t("agents_ui.every_v", { v });
+  }
+  if (s.startsWith("once:")) return `once · ${new Date(s.slice(5)).toLocaleString()}`;
+  if (s.startsWith("cron ")) return `cron · ${s.slice(5)}`;
+  return s;
+}
+
+export function schedPresets() {
+  return [
+    { label: t("agents_ui.preset_every_10m"), value: "every:10m" },
+    { label: t("agents_ui.preset_hourly"), value: "every:1h" },
+    { label: t("agents_ui.preset_daily_9am"), value: "cron 0 9 * * *" },
+    { label: t("agents_ui.preset_weekdays_9am"), value: "cron 0 9 * * 1-5" },
+  ];
+}
+
+// Template/env vars the routine runner exposes (src/core/routines/runner.js).
+export function routineVars() {
+  return [
+    { v: "{{pre_output}}", where: "prompt", desc: t("agents_ui.var_pre_output_prompt") },
+    { v: "$APX_LLM_OUTPUT", where: "post", desc: t("agents_ui.var_llm_output") },
+    { v: "$APX_STATUS", where: "post", desc: t("agents_ui.var_status") },
+    { v: "$APX_SKIPPED", where: "post", desc: t("agents_ui.var_skipped") },
+    { v: "$APX_PRE_OUTPUT", where: "post", desc: t("agents_ui.var_pre_output") },
+    { v: "$APX_PRE_OUTPUT_FILE", where: "post", desc: t("agents_ui.var_pre_output_file") },
+    { v: "$APX_PRE_EXIT", where: "post", desc: t("agents_ui.var_pre_exit") },
+    { v: "$APX_ROUTINE", where: "pre/post", desc: t("agents_ui.var_routine") },
+  ];
+}
+
+// Which variables belong under which textarea:
+//   pre    → vars usable in pre-commands ($APX_ROUTINE)
+//   prompt → template vars for the prompt / telegram text ({{pre_output}})
+//   post   → env vars for post-commands ($APX_*)
+export function varsFor(ctx: "pre" | "prompt" | "post") {
+  return routineVars().filter((v) => {
+    if (ctx === "pre") return v.where.includes("pre");
+    if (ctx === "prompt") return v.where === "prompt";
+    return v.where === "post" || v.where === "pre/post";
+  });
+}

package/src/interfaces/web/src/components/settings/PairDeviceDialog.tsx

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 import { Copy } from "lucide-react";
 import { Dialog, Button, Spinner } from "../ui";
+import { Tip } from "../ui/tip";
 import { Qr } from "../common/Qr";
 import { useToast } from "../Toast";
 import { Pair, HttpError } from "../../lib/api";
@@ -138,14 +139,15 @@ export function PairDeviceDialog({
                     <code className="min-w-0 flex-1 break-all rounded-md bg-muted px-3 py-2 text-xs">
                       {scanUrl}
                     </code>
-                    <Button
-                      size="sm"
-                      variant="secondary"
-                      onClick={() => copy(scanUrl, t("settings.devices_pair_copied"))}
-                      title={t("settings.devices_pair_copy")}
-                    >
-                      <Copy size={14} />
-                    </Button>
+                    <Tip content={t("settings.devices_pair_copy")}>
+                      <Button
+                        size="sm"
+                        variant="secondary"
+                        onClick={() => copy(scanUrl, t("settings.devices_pair_copied"))}
+                      >
+                        <Copy size={14} />
+                      </Button>
+                    </Tip>
                   </div>
                 </div>
 
@@ -155,14 +157,15 @@ export function PairDeviceDialog({
                     <code className="min-w-0 flex-1 break-all rounded-md bg-muted px-3 py-2 text-center text-sm">
                       {init.pairing_id}
                     </code>
-                    <Button
-                      size="sm"
-                      variant="secondary"
-                      onClick={() => copy(init.pairing_id, t("settings.devices_pair_copied_code"))}
-                      title={t("settings.devices_pair_copy")}
-                    >
-                      <Copy size={14} />
-                    </Button>
+                    <Tip content={t("settings.devices_pair_copy")}>
+                      <Button
+                        size="sm"
+                        variant="secondary"
+                        onClick={() => copy(init.pairing_id, t("settings.devices_pair_copied_code"))}
+                      >
+                        <Copy size={14} />
+                      </Button>
+                    </Tip>
                   </div>
                 </div>
               </div>

package/src/interfaces/web/src/components/settings/TelegramContactsPanel.tsx

@@ -4,6 +4,7 @@
 
 import { Section } from "../Section";
 import { Badge, Button, Empty, Loading, Select } from "../ui";
+import { Tip } from "../ui/tip";
 import { useToast } from "../Toast";
 import { useTelegramContacts } from "../../hooks/useTelegram";
 import { Telegram } from "../../lib/api";
@@ -58,14 +59,15 @@ export function TelegramContactsPanel({ bare = false }: Props) {
                     {isOwner && <Badge tone="success">{t("telegram_contacts.owner_badge")}</Badge>}
                   </div>
                   <div className="flex items-center gap-2">
-                    <Select
-                      value={effectiveRole}
-                      disabled={isOwner}
-                      onChange={(e) => setRole(c, e.target.value)}
-                      title={isOwner ? t("telegram_contacts.owner_hint") : t("telegram_contacts.assign_role")}
-                    >
-                      {roleNames.map((r) => <option key={r} value={r}>{r}</option>)}
-                    </Select>
+                    <Tip content={isOwner ? t("telegram_contacts.owner_hint") : t("telegram_contacts.assign_role")}>
+                      <Select
+                        value={effectiveRole}
+                        disabled={isOwner}
+                        onChange={(e) => setRole(c, e.target.value)}
+                      >
+                        {roleNames.map((r) => <option key={r} value={r}>{r}</option>)}
+                      </Select>
+                    </Tip>
                     <Button size="sm" variant="destructive" onClick={() => remove(c)}>{t("common.delete")}</Button>
                   </div>
                 </div>