@indianic/dialout 1.13.2 → 1.14.0

package/node_modules/@indianic/dialout-shared/src/custom-agents.test.ts

@@ -0,0 +1,185 @@
+import { describe, it, expect } from 'vitest';
+import {
+  parseCustomAgent,
+  parseCustomAgents,
+  customAgentRule,
+  expandTranscript,
+  transcriptMatcher,
+  isAiKind,
+} from './custom-agents';
+
+const good = {
+  name: 'sagent',
+  kind: 'claude' as const,
+  transcript: '{home}/.myagent/sessions/*.jsonl',
+};
+
+describe('parseCustomAgent', () => {
+  it('accepts a well-formed declaration', () => {
+    const parsed = parseCustomAgent(good);
+    expect(parsed).toEqual({ ok: true, agent: good });
+  });
+
+  it('trims and lowercases the kind, so "Claude" is not a mystery failure', () => {
+    const parsed = parseCustomAgent({ ...good, kind: '  Claude ' });
+    expect(parsed.ok && parsed.agent.kind).toBe('claude');
+  });
+
+  it('rejects a kind with no adapter behind it', () => {
+    // The whole point: `kind` chooses which parser runs. A kind we have no
+    // adapter for would produce a session with no conversation in it.
+    const parsed = parseCustomAgent({ ...good, kind: 'augment-next' });
+    expect(parsed.ok).toBe(false);
+  });
+
+  describe('the path rules, which are the security boundary', () => {
+    // The agent runs as the user and streams whatever it is pointed at into a
+    // chat. These rules are what stop a declaration being a way to read
+    // arbitrary files.
+
+    it('requires the path to start at {home}', () => {
+      for (const transcript of ['/etc/passwd', '~/.ssh/id_rsa', '/{home}/x.jsonl', 'relative/x.jsonl']) {
+        const parsed = parseCustomAgent({ ...good, transcript });
+        expect(parsed.ok, transcript).toBe(false);
+      }
+    });
+
+    it('rejects traversal outright', () => {
+      const parsed = parseCustomAgent({ ...good, transcript: '{home}/../../etc/hosts.jsonl' });
+      expect(parsed.ok).toBe(false);
+    });
+
+    it('requires a .json or .jsonl file, so {home}/.ssh/* is not declarable', () => {
+      const parsed = parseCustomAgent({ ...good, transcript: '{home}/.ssh/*' });
+      expect(parsed.ok).toBe(false);
+      expect(parseCustomAgent({ ...good, transcript: '{home}/.x/a.json' }).ok).toBe(true);
+      expect(parseCustomAgent({ ...good, transcript: '{home}/.x/a.jsonl' }).ok).toBe(true);
+    });
+
+    it('allows a glob only in the file name', () => {
+      // A '*' in a directory segment would walk the home directory.
+      expect(parseCustomAgent({ ...good, transcript: '{home}/*/sessions/a.jsonl' }).ok).toBe(false);
+      expect(parseCustomAgent({ ...good, transcript: '{home}/.x/*.jsonl' }).ok).toBe(true);
+    });
+
+    it('allows at most one glob', () => {
+      expect(parseCustomAgent({ ...good, transcript: '{home}/.x/*-*.jsonl' }).ok).toBe(false);
+    });
+
+    it('reports an unknown placeholder instead of looking up a literal directory', () => {
+      const parsed = parseCustomAgent({ ...good, transcript: '{home}/.x/{sessionid}/a.jsonl' });
+      expect(parsed.ok).toBe(false);
+      expect(parsed.ok === false && parsed.error).toContain('{sessionid}');
+    });
+  });
+
+  describe('the name rules', () => {
+    it('rejects a name that would match half the process table', () => {
+      for (const name of ['', ' ', '*', '.*', 'my agent', 'bin/agent', 'a'.repeat(65)]) {
+        expect(parseCustomAgent({ ...good, name }).ok, JSON.stringify(name)).toBe(false);
+      }
+    });
+
+    it('accepts the characters real binaries use', () => {
+      for (const name of ['agy', 'my-agent', 'my_agent', 'agent.sh', 'claude2', 'c++agent']) {
+        expect(parseCustomAgent({ ...good, name }).ok, name).toBe(true);
+      }
+    });
+  });
+
+  it('rejects junk rather than throwing', () => {
+    for (const bad of [null, undefined, 42, 'str', [], {}]) {
+      expect(parseCustomAgent(bad).ok).toBe(false);
+    }
+  });
+});
+
+describe('parseCustomAgents', () => {
+  it('treats absent as none', () => {
+    expect(parseCustomAgents(undefined)).toEqual({ ok: true, agents: [] });
+    expect(parseCustomAgents(null)).toEqual({ ok: true, agents: [] });
+  });
+
+  it('reports the first bad entry rather than silently dropping it', () => {
+    // Silently dropping would leave the user with a config they can see and a
+    // session they cannot, and nothing connecting the two.
+    const parsed = parseCustomAgents([good, { ...good, name: 'x', kind: 'nope' }]);
+    expect(parsed.ok).toBe(false);
+  });
+
+  it('rejects two entries claiming one name', () => {
+    const parsed = parseCustomAgents([good, { ...good, transcript: '{home}/.other/a.json' }]);
+    expect(parsed.ok).toBe(false);
+    expect(parsed.ok === false && parsed.error).toContain('duplicate');
+  });
+
+  it('rejects a non-array', () => {
+    expect(parseCustomAgents({ name: 'x' }).ok).toBe(false);
+  });
+});
+
+describe('customAgentRule', () => {
+  const rule = (name: string) => customAgentRule({ ...good, name });
+
+  it('anchors on a path-segment boundary, like the built-in rules', () => {
+    expect(rule('sagent').test('sagent')).toBe(true);
+    expect(rule('sagent').test('sagent --resume')).toBe(true);
+    expect(rule('sagent').test('/usr/local/bin/sagent')).toBe(true);
+    // A bare space before the name is neither start-of-string nor a slash.
+    expect(rule('sagent').test('vim sagent')).toBe(false);
+    expect(rule('sagent').test('sagentry')).toBe(false);
+  });
+
+  it('escapes the name, so a declaration cannot inject a pattern', () => {
+    // '.' must match a literal dot and nothing else; without escaping,
+    // 'a.y' would match 'agy' — and a name of '.*' would match everything.
+    expect(rule('a.y').test('a.y')).toBe(true);
+    expect(rule('a.y').test('agy')).toBe(false);
+  });
+});
+
+describe('expandTranscript', () => {
+  it('fills the placeholders it is given', () => {
+    expect(expandTranscript('{home}/.x/{pid}/a.jsonl', { home: '/h', pid: 42 }))
+      .toBe('/h/.x/42/a.jsonl');
+    expect(expandTranscript('{home}/.x/{tty}.json', { home: '/h', tty: '/dev/ttys1' }))
+      .toBe('/h/.x//dev/ttys1.json');
+  });
+
+  it('returns null when a placeholder it needs has no value', () => {
+    // Otherwise '{cwd}' is looked up as a literal directory of that name,
+    // which never matches and reads as "your declaration is wrong".
+    expect(expandTranscript('{home}/.x/{cwd}/a.jsonl', { home: '/h' })).toBeNull();
+    expect(expandTranscript('{home}/.x/a.jsonl', { home: '' })).toBeNull();
+  });
+});
+
+describe('transcriptMatcher', () => {
+  it('matches an exact file name when there is no glob', () => {
+    const m = transcriptMatcher('/h/.x/chat.jsonl');
+    expect(m.dir).toBe('/h/.x');
+    expect(m.match('chat.jsonl')).toBe(true);
+    expect(m.match('other.jsonl')).toBe(false);
+  });
+
+  it('expands a glob within the file name only', () => {
+    const m = transcriptMatcher('/h/.x/*.jsonl');
+    expect(m.dir).toBe('/h/.x');
+    expect(m.match('a.jsonl')).toBe(true);
+    expect(m.match('deep/a.jsonl')).toBe(false);
+    expect(m.match('a.json')).toBe(false);
+  });
+
+  it('treats the non-glob part of the name literally', () => {
+    const m = transcriptMatcher('/h/.x/roll.out-*.jsonl');
+    expect(m.match('roll.out-1.jsonl')).toBe(true);
+    expect(m.match('rollXout-1.jsonl')).toBe(false);
+  });
+});
+
+describe('isAiKind', () => {
+  it('knows the four vendors with adapters', () => {
+    for (const k of ['claude', 'codex', 'grok', 'augment']) expect(isAiKind(k)).toBe(true);
+    for (const k of ['gemini', '', null, undefined, 7]) expect(isAiKind(k)).toBe(false);
+  });
+});

package/node_modules/@indianic/dialout-shared/src/custom-agents.ts

@@ -0,0 +1,198 @@
+import type { AiKind } from './kinds';
+
+/**
+ * A coding agent this machine's owner has declared by hand.
+ *
+ * Two cases this exists for, and one it deliberately does not cover.
+ *
+ * It covers a RENAMED BINARY — a copy of a supported CLI living under another
+ * name, where argv really is `sagent` and the detector's rules cannot see it.
+ * And it covers a supported format written somewhere we do not look.
+ *
+ * It does NOT make a genuinely new vendor readable. `kind` chooses which
+ * existing parser runs, so a custom agent must write a transcript one of the
+ * adapters already understands. There is no way around that: knowing a process
+ * is an agent tells you nothing about how to read its conversation.
+ *
+ * Worth being clear about what is NOT needed here: a shell alias, function or
+ * wrapper script needs no entry at all. `sagent() { claude "$@"; }` runs a
+ * process whose argv is `claude`, and findAgentInPane walks descendants, so it
+ * is already detected. Only a renamed binary is invisible.
+ *
+ * ---
+ *
+ * MACHINE-LOCAL BY DESIGN. These live in ~/.dialout/config.json and are never
+ * accepted from the server.
+ *
+ * The agent runs as the user, with the user's full read access, and it streams
+ * whatever it is pointed at into a chat. A server-supplied path would therefore
+ * be a file-read primitive: point it at ~/.ssh/id_rsa or a .env and the
+ * contents leave the machine. Keeping the declaration on the machine means
+ * compromising a web account cannot turn every agent into a file reader — the
+ * same reasoning that keeps the ws-server bound to 127.0.0.1 and filters every
+ * value interpolated into the cowork rc block.
+ *
+ * The validation below is the second line of defence, not the first.
+ */
+export interface CustomAgent {
+  /** The command name as the process table shows it, e.g. 'sagent'. */
+  name: string;
+  /** Which existing adapter reads this agent's transcript. */
+  kind: AiKind;
+  /** Where the transcript lives; see expandTranscript for the placeholders. */
+  transcript: string;
+}
+
+export const AI_KINDS: readonly AiKind[] = ['claude', 'codex', 'grok', 'augment'] as const;
+
+export function isAiKind(value: unknown): value is AiKind {
+  return typeof value === 'string' && (AI_KINDS as readonly string[]).includes(value);
+}
+
+/**
+ * A command name, not a pattern.
+ *
+ * No spaces and no path separators: the value is matched against one argv
+ * token, and anything looser invites an entry that matches every process on
+ * the machine. The characters allowed are the ones real binaries use.
+ */
+const NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$/;
+
+/** The placeholders expandTranscript understands. Anything else is a typo worth reporting. */
+export const TRANSCRIPT_VARS = ['home', 'cwd', 'tty', 'pid'] as const;
+const VAR_RE = /\{([a-z]+)\}/g;
+
+export type CustomAgentParse =
+  | { ok: true; agent: CustomAgent }
+  | { ok: false; error: string };
+
+export function parseCustomAgent(input: unknown): CustomAgentParse {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return { ok: false, error: 'A custom agent must be an object' };
+  }
+  const raw = input as Record<string, unknown>;
+  const name = typeof raw.name === 'string' ? raw.name.trim() : '';
+  const kind = typeof raw.kind === 'string' ? raw.kind.trim().toLowerCase() : '';
+  const transcript = typeof raw.transcript === 'string' ? raw.transcript.trim() : '';
+
+  if (!NAME_RE.test(name)) {
+    return { ok: false, error: 'name must be a bare command name, e.g. sagent (letters, digits, . _ + -)' };
+  }
+  if (!isAiKind(kind)) {
+    return { ok: false, error: `kind must be one of ${AI_KINDS.join(', ')}` };
+  }
+  if (!transcript) {
+    return { ok: false, error: 'transcript is required' };
+  }
+  // Anchored at {home} so a declaration cannot reach outside the user's own
+  // files even before the resolved path is re-checked.
+  if (!transcript.startsWith('{home}/')) {
+    return { ok: false, error: 'transcript must start with {home}/' };
+  }
+  if (transcript.includes('..')) {
+    return { ok: false, error: 'transcript must not contain ..' };
+  }
+  // A transcript is a file we parse, so the extension is part of the contract.
+  // Without this, `{home}/.ssh/*` is a legal declaration.
+  if (!/\.jsonl?$/.test(transcript)) {
+    return { ok: false, error: 'transcript must end in .json or .jsonl' };
+  }
+  // At most one glob, and only in the filename: a `*` in a directory segment
+  // would walk the home directory.
+  const slash = transcript.lastIndexOf('/');
+  if (transcript.slice(0, slash).includes('*')) {
+    return { ok: false, error: 'a * may only appear in the file name, not in a directory' };
+  }
+  if ((transcript.match(/\*/g) || []).length > 1) {
+    return { ok: false, error: 'transcript may contain at most one *' };
+  }
+  const unknown = [...transcript.matchAll(VAR_RE)]
+    .map((m) => m[1])
+    .filter((v) => !(TRANSCRIPT_VARS as readonly string[]).includes(v));
+  if (unknown.length) {
+    return {
+      ok: false,
+      error: `unknown placeholder {${unknown[0]}}; use ${TRANSCRIPT_VARS.map((v) => `{${v}}`).join(', ')}`,
+    };
+  }
+  return { ok: true, agent: { name, kind, transcript } };
+}
+
+/** Parses a list, reporting the first bad entry rather than silently dropping it. */
+export function parseCustomAgents(input: unknown): { ok: true; agents: CustomAgent[] } | { ok: false; error: string } {
+  if (input === undefined || input === null) return { ok: true, agents: [] };
+  if (!Array.isArray(input)) return { ok: false, error: 'customAgents must be an array' };
+  const agents: CustomAgent[] = [];
+  const seen = new Set<string>();
+  for (const entry of input) {
+    const parsed = parseCustomAgent(entry);
+    if (!parsed.ok) return parsed;
+    if (seen.has(parsed.agent.name)) {
+      return { ok: false, error: `duplicate custom agent name: ${parsed.agent.name}` };
+    }
+    seen.add(parsed.agent.name);
+    agents.push(parsed.agent);
+  }
+  return { ok: true, agents };
+}
+
+function escapeRegExp(text: string): string {
+  return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+/**
+ * The detector rule for a custom name.
+ *
+ * Built with the same path-segment anchoring as the built-in rules, so
+ * `sagent` and `/usr/local/bin/sagent` match while `vim sagent` and
+ * `sagentry` do not. The name is escaped, so a declaration can never inject
+ * a pattern — `.*` is matched literally, not as a wildcard.
+ */
+export function customAgentRule(agent: CustomAgent): RegExp {
+  return new RegExp(`(^|/)${escapeRegExp(agent.name)}(\\s|$)`);
+}
+
+export interface TranscriptVars {
+  home: string;
+  cwd?: string;
+  tty?: string;
+  pid?: number;
+}
+
+/**
+ * Fill in a transcript template.
+ *
+ * Returns null when a placeholder the template uses has no value — an
+ * unresolved `{cwd}` would otherwise be looked up as a literal directory
+ * called "{cwd}", which silently never matches and looks like the user's
+ * declaration was wrong.
+ */
+export function expandTranscript(template: string, vars: TranscriptVars): string | null {
+  let missing = false;
+  const out = template.replace(VAR_RE, (_whole, name: string) => {
+    const value = name === 'home' ? vars.home
+      : name === 'cwd' ? vars.cwd
+      : name === 'tty' ? vars.tty
+      : name === 'pid' ? (vars.pid === undefined ? undefined : String(vars.pid))
+      : undefined;
+    if (!value) { missing = true; return ''; }
+    return value;
+  });
+  return missing ? null : out;
+}
+
+/**
+ * Split an expanded template into the directory to list and a matcher for the
+ * file name. A template with no `*` still goes through this, so one code path
+ * handles both.
+ */
+export function transcriptMatcher(expanded: string): { dir: string; match: (name: string) => boolean } {
+  const slash = expanded.lastIndexOf('/');
+  const dir = expanded.slice(0, slash) || '/';
+  const base = expanded.slice(slash + 1);
+  if (!base.includes('*')) {
+    return { dir, match: (name: string) => name === base };
+  }
+  const re = new RegExp(`^${base.split('*').map(escapeRegExp).join('[^/]*')}$`);
+  return { dir, match: (name: string) => re.test(name) };
+}

package/node_modules/@indianic/dialout-shared/src/index.ts

@@ -1,4 +1,9 @@
 export type { AiKind } from './kinds';
+export type { CustomAgent, CustomAgentParse, TranscriptVars } from './custom-agents';
+export {
+  AI_KINDS, isAiKind, parseCustomAgent, parseCustomAgents,
+  customAgentRule, expandTranscript, transcriptMatcher, TRANSCRIPT_VARS,
+} from './custom-agents';
 
 export type { AiStatus, AiEvent, AiAdapter } from './events';
 export { PREVIEW_LIMIT, preview } from './events';

package/node_modules/@indianic/dialout-shared/src/kinds.ts

@@ -2,4 +2,4 @@
 // break the week a fourth is added — treat an unknown kind as generic at
 // runtime (string on the wire, this union at compile time for the ones we
 // have adapters for).
-export type AiKind = 'claude' | 'codex' | 'grok';
+export type AiKind = 'claude' | 'codex' | 'grok' | 'augment';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indianic/dialout",
-  "version": "1.13.2",
+  "version": "1.14.0",
   "description": "Dialout agent — reach your office, home or build machine from any browser or phone. Remote tmux terminals, live port checks, filesystem browsing, process control and HTTP tunnels. The agent dials out: no inbound ports, no VPN, no port forwarding.",
   "bin": {
     "dialout": "./bin/devdash-agent.js"