@andrian.yablonskyy/thub-agent 1.0.0

package/README.md

@@ -0,0 +1,139 @@
+# @andrian.yablonskyy/thub-agent
+
+The Agent CLI (`thub`) for [TestHub](https://github.com/andrianyablonskyy/thub) — a self-hosted job network that lets CI/CD pipelines and individual developers run firmware tests on real hardware or emulators in a private lab. `thub` is the single entry point for both: it's stateless, everything it knows comes from the [Coordinator](https://github.com/andrianyablonskyy/thub-coordinator) API, and it runs identically on a GitHub-hosted runner and a developer laptop — a developer reproducing a CI failure runs exactly the same command the pipeline runs.
+
+See the [main TestHub repo](https://github.com/andrianyablonskyy/thub) for the full system architecture and how this fits with the Coordinator and the [Client](https://github.com/andrianyablonskyy/thub-client).
+
+## Install
+
+```bash
+npm install -g @andrian.yablonskyy/thub-agent
+# or, one-off in CI:
+npx -y @andrian.yablonskyy/thub-agent run --type sw --image "$IMAGE_URL" --tests "$TESTS_URL" --wait
+```
+
+## Configuration
+
+Read from flags, then environment (`THUB_URL`, `THUB_TOKEN`, `THUB_GROUP`, `THUB_USER`), then `~/.config/thub/config.json`, then a bundled default. `url`/`token` are required by the time a command actually talks to the Coordinator; `group`/`user` are optional everywhere.
+
+```bash
+thub config set url https://thub.example.com
+thub config set token agt_...
+thub config set group 548ae4ae-...   # optional default --group
+thub config set user "Your Name"     # optional default --user
+```
+
+## Commands
+
+```
+thub run      [options]        Submit a test job and follow its log
+thub status   <jobId>          Show status; follow log if running, show artifacts if done
+thub cancel   <jobId>          Cancel a job
+thub resources                 List resources and their status
+thub jobs     [--mine] [--state <s>]   List recent jobs
+thub config   set <key> <value>        Save coordinator URL / token / default group / default user locally
+```
+
+Key options for `thub run`:
+
+| Option | Description |
+|---|---|
+| `--type hw\|sw` | Required resource type. |
+| `--board <name>` / `--label <l>` | Required labels (repeatable). |
+| `--group <groupId>` | Restrict scheduling to resources that are members of this group. Falls back to `THUB_GROUP` / `thub config set group <id>`. |
+| `--user <name>` | Free-text job owner — a label, not an identity. Falls back to `THUB_USER` / `thub config set user <name>`. |
+| `--image <url>` | Firmware/build image URL, fetched by the Client. |
+| `--sha256 <hex>` | Expected sha256 of `--image`; the Client verifies it before flashing/running. |
+| `--tests <url>` / `--suite <name>` | Test package and suite. |
+| `--arg <value>` | Extra argument passed through to `run-tests.sh` on the Client (repeatable). |
+| `--timeout <dur>` | e.g. `30m`, default `30m`. |
+| `--priority <n>` | 0–100; CI defaults to 50, CLI to 60 so a developer is not starved by a busy pipeline. |
+| `--meta <key=value>` | Arbitrary metadata stored on the job (repeatable) — CI job ids, git coordinates, anything else worth attaching to the run. |
+| `--source ci\|cli` | Override auto-detected job source (defaults to `ci` when `$GITHUB_ACTIONS=true`, else `cli`). |
+| `--dry-run` | Exercise the full pipeline without the Client executing anything for real. |
+| `--wait` | Do not detach on job end; exit with the job's verdict code (used in CI). |
+| `--detach` | Print the job id and exit immediately. |
+| `--json` | Machine-readable output. |
+
+- `thub run` prints the **job ID**, then streams logs until Ctrl-C. Ctrl-C detaches; the job keeps running on the Client.
+- `thub status <jobId>` prints the current state; if active it keeps streaming, if done it prints the verdict and artifact download links.
+
+Exit codes make the Agent usable as a CI step:
+
+| Code | Meaning |
+|---|---|
+| `0` | `PASSED` |
+| `1` | `FAILED` |
+| `2` | `ERROR`, `TIMEOUT`, or `LOST` |
+| `3` | `CANCELED` |
+| `4` | Usage, auth or connection error |
+| `130` | Detached with Ctrl-C (job still running) |
+
+## Examples
+
+**Associate a CI/CD job id with the internal job id:**
+
+```bash
+thub run --type sw --image "$IMAGE_URL" --tests "$TESTS_URL" \
+  --meta ciJobId="$GITHUB_RUN_ID" --wait
+thub status A-00123 --json | jq '.spec.meta.ciJobId'
+```
+
+**Pass Git repo/branch/hash/tag to the Client** — these travel as `--meta key=value` and the Client exposes each one to `run-tests.sh` as `THUB_META_<KEY>` (`ciJobId` → `THUB_META_CI_JOB_ID`):
+
+```bash
+thub run --type hw --board nucleo-f401re \
+  --image "$IMAGE_URL" --tests "$TESTS_URL" --suite smoke \
+  --meta repo=yourorg/firmware --meta branch=main --meta sha=a1b2c3d --wait
+```
+
+**Dry-run the pipeline** — proves the Coordinator↔Client plumbing works without real hardware, a real emulator image, or a reachable Artifactory:
+
+```bash
+thub run --type sw --image https://does-not-exist.invalid/app.bin \
+  --tests https://does-not-exist.invalid/tests.tar.gz --suite smoke \
+  --dry-run --wait
+```
+
+**Run on a specific resource group only:**
+
+```bash
+thub run --type sw --image "$IMAGE_URL" --tests "$TESTS_URL" \
+  --group 548ae4ae-ac5b-401f-acaa-24bbe790e62d --wait
+```
+
+**Label a job with its owner** — purely informational, shows up on the dashboard, in `thub jobs`, and on the Client's own console:
+
+```bash
+thub run --type hw --board nucleo-f401re \
+  --image "$IMAGE_URL" --tests "$TESTS_URL" --user "Your Name" --wait
+```
+
+## GitHub Actions
+
+```yaml
+test-sw:
+  needs: build
+  runs-on: ubuntu-latest
+  env:
+    THUB_URL: https://thub.example.com
+    THUB_TOKEN: ${{ secrets.THUB_AGENT_TOKEN }}
+  steps:
+    - run: |
+        npx -y @andrian.yablonskyy/thub-agent run --type sw \
+          --image "${{ needs.build.outputs.image_url }}" \
+          --tests "${{ needs.build.outputs.tests_url }}" --suite full --wait
+```
+
+If the GitHub job is canceled, the runner sends `SIGINT` to the Agent. In `--wait` mode (CI), that's treated as a cancel request (`POST /jobs/:id/cancel`) before exiting, so abandoned CI jobs don't hold hardware. In interactive mode, Ctrl-C only detaches.
+
+## Development
+
+```bash
+npm install
+npm run lint
+```
+
+## License
+
+Proprietary — see the header comment in each source file.

package/config.json

@@ -0,0 +1,6 @@
+{
+  "url": "http://localhost:8000",
+  "token": "agt_0CckgVh8wCMJpNkNpS7EBBeYJ8RCQ9LFIKUCYmZJ8oY",
+  "group": "",
+  "user": ""
+}

package/eslint.config.js

@@ -0,0 +1,97 @@
+/**
+ * @file        eslint.config.js
+ * @description ESLint flat config for @andrian.yablonskyy/thub-agent: stylistic/promise rules plus Node globals
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const stylistic = require('@stylistic/eslint-plugin'),
+  promise = require('eslint-plugin-promise'),
+  globals = require('globals');
+
+module.exports = [
+  { ignores: ['**/node_modules/**'] },
+  {
+    files: ['**/*.{js,cjs,mjs}'],
+    plugins: { '@stylistic': stylistic, promise },
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'commonjs',
+      globals: { ...globals.node }
+    },
+    rules: {
+      // Core JS
+      'prefer-const': 'error',
+      strict: ['error', 'global'],
+      camelcase: [
+        'error',
+        {
+          properties: 'never',
+          ignoreGlobals: true,
+          ignoreDestructuring: true,
+          allow: ['[a-z]+([a-z0-9_])?']
+        }
+      ],
+      'one-var': ['error', { var: 'never', let: 'consecutive', const: 'consecutive' }],
+      'no-var': 'error',
+      // console.log/error *is* this CLI's actual output mechanism (job
+      // status, tables, error messages), not leftover debugging.
+      'no-console': 'off',
+      'no-restricted-syntax': [
+        'error',
+        {
+          selector: 'CallExpression[callee.object.name="console"][callee.property.name!=/^(log|warn|error|info|trace)$/]',
+          message: 'Unexpected property on console object was called'
+        }
+      ],
+      curly: 'error',
+
+      // Stylistic
+      '@stylistic/indent': ['error', 2],
+      '@stylistic/key-spacing': ['error', { beforeColon: false, afterColon: true, mode: 'strict' }],
+      '@stylistic/keyword-spacing': ['error', { before: false, after: true }],
+      '@stylistic/linebreak-style': ['error', 'unix'],
+      '@stylistic/space-before-function-paren': ['error', { anonymous: 'always', named: 'never', asyncArrow: 'always' }],
+      '@stylistic/space-infix-ops': 'error',
+      '@stylistic/space-before-blocks': ['error', 'never'],
+      '@stylistic/comma-dangle': ['error', 'never'],
+      '@stylistic/max-len': ['error', 160],
+      '@stylistic/no-trailing-spaces': ['error', { skipBlankLines: false }],
+      '@stylistic/no-multiple-empty-lines': ['error', { max: 1 }],
+      '@stylistic/semi': ['error', 'always'],
+      '@stylistic/quotes': ['error', 'single'],
+      '@stylistic/one-var-declaration-per-line': ['error', 'always'],
+      '@stylistic/no-extra-semi': 'error',
+      '@stylistic/no-multi-spaces': 'error',
+      '@stylistic/no-mixed-spaces-and-tabs': 'error',
+      '@stylistic/arrow-parens': ['error', 'always'],
+      '@stylistic/arrow-spacing': ['error', { before: true, after: true }],
+      '@stylistic/block-spacing': 'error',
+      '@stylistic/brace-style': ['error', 'stroustrup'],
+      '@stylistic/comma-spacing': ['error', { before: false, after: true }],
+      '@stylistic/comma-style': ['error', 'last'],
+      '@stylistic/dot-location': ['error', 'property'],
+      '@stylistic/function-call-spacing': ['error', 'never'],
+
+      // Promises
+      'promise/always-return': ['error', { ignoreLastCallback: true }],
+      'promise/param-names': 'off',
+      'promise/catch-or-return': ['error', { allowFinally: true }],
+      'promise/no-native': 'off',
+      'promise/no-nesting': 'off',
+      'promise/no-callback-in-promise': 'off',
+      'promise/avoid-new': 'off',
+      'promise/no-new-statics': 'error',
+      'promise/no-return-in-finally': 'warn',
+      'promise/valid-params': 'warn'
+    }
+  }
+];

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@andrian.yablonskyy/thub-agent",
+  "version": "1.0.0",
+  "description": "TestHub Agent CLI — the single entry point CI/CD and developers use to submit and follow test jobs",
+  "bin": {
+    "thub": "./src/cli.js"
+  },
+  "main": "src/cli.js",
+  "scripts": {
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  },
+  "dependencies": {
+    "@andrian.yablonskyy/thub-common": "*",
+    "commander": "^13.1.0"
+  },
+  "devDependencies": {
+    "@stylistic/eslint-plugin": "^5.10.0",
+    "eslint": "^10.11.0",
+    "eslint-plugin-promise": "^7.3.0",
+    "globals": "^17.12.0"
+  }
+}

package/src/cli.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+
+/**
+ * @file        packages/agent/src/cli.js
+ * @description thub CLI entry point: run/status/cancel/resources/jobs/config commands (README §7)
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const { Command } = require('commander'),
+  { ApiClient, EXIT_CODES, ACTIVE_JOB_STATES, exitCodeForJobState } = require('@andrian.yablonskyy/thub-common'),
+  { resolveConnection, resolveGroup, resolveUser, writeConfigFile, readConfigFile } = require('./config'),
+  { parseDurationSec } = require('./duration'),
+  { followJob } = require('./streaming');
+
+const program = new Command();
+program
+  .name('thub')
+  .description('TestHub Agent — submit test jobs and follow them, from CI or your laptop')
+  .option('--url <url>', 'Coordinator URL (overrides THUB_URL / config file)')
+  .option('--token <token>', 'Agent token (overrides THUB_TOKEN / config file)');
+
+function client(){
+  const { url, token } = resolveConnection(program.opts());
+  return new ApiClient({ baseUrl: url, token });
+}
+
+function fail(err){
+  console.error(`Error: ${err.message}`);
+  process.exit(err.status && Number.isInteger(err.status) && err.status < 100 ? err.status : EXIT_CODES.USAGE);
+}
+
+program
+  .command('run')
+  .description('Submit a test job and follow its log')
+  .requiredOption('--type <hw|sw>', 'Required resource type')
+  .option('--board <name>', 'Shorthand for --label board:<name>')
+  .option('--label <label>', 'Required label the resource must have (repeatable)', collectRepeatable, [])
+  .option(
+    '--group <groupId>',
+    'Restrict scheduling to resources that are members of this group (§13.1). ' +
+      'Overrides THUB_GROUP / config file; leave unset for an unconstrained run.'
+  )
+  .option(
+    '--user <name>',
+    'Free-text job owner, shown on the Client and the dashboard to tell whose job is whose ' +
+      '— purely a label, not an identity. Overrides THUB_USER / config file.'
+  )
+  .requiredOption('--image <url>', 'Firmware/build image URL (Artifactory or a Docker registry blob) fetched by the Client')
+  .option('--sha256 <hex>', 'Expected sha256 of --image; the Client verifies it before flashing/running')
+  .requiredOption('--tests <url>', 'Test package URL in Artifactory')
+  .option('--suite <name>', 'Test suite name', 'default')
+  .option('--arg <value>', 'Extra argument passed through to run-tests.sh on the Client (repeatable)', collectRepeatable, [])
+  .option('--timeout <duration>', 'e.g. 30m, 1h', '30m')
+  .option('--priority <n>', 'Priority 0-100', (v) => Number(v))
+  .option('--wait', 'Do not detach on job end; exit with the verdict code (used in CI)', false)
+  .option('--detach', 'Print the job id and exit immediately', false)
+  .option('--json', 'Machine-readable output', false)
+  .option(
+    '--meta <keyValue>',
+    'Extra metadata key=value, stored on the job and returned by `thub status --json` (repeatable). ' +
+      'Use this to carry CI job ids, git repo/branch/sha/tag, or anything else you want attached to the run.',
+    collectRepeatable,
+    []
+  )
+  .option('--source <ci|cli>', 'Override auto-detected job source')
+  .option(
+    '--dry-run',
+    'Exercise the full pipeline (schedule, accept, state transitions, logs, artifact, result) ' +
+      'without the Client flashing/running anything for real',
+    false
+  )
+  .action(async (opts) => {
+    try {
+      const c = client(),
+        source = opts.source || (process.env.GITHUB_ACTIONS === 'true' ? 'ci' : 'cli'),
+        labels = [...(opts.board ? [`board:${opts.board}`] : []), ...opts.label],
+        meta = Object.fromEntries(opts.meta.map((kv) => kv.split(/=(.*)/s).slice(0, 2))),
+        group = resolveGroup({ group: opts.group }),
+        user = resolveUser({ user: opts.user }),
+
+        spec = {
+          target: { type: opts.type, labels, ...(group ? { group } : {}) },
+          firmware: { url: opts.image, ...(opts.sha256 ? { sha256: opts.sha256 } : {}) },
+          tests: { url: opts.tests, suite: opts.suite, args: opts.arg },
+          timeoutSec: parseDurationSec(opts.timeout),
+          priority: opts.priority ?? (source === 'ci' ? 50 : 60),
+          source,
+          ...(user ? { user } : {}),
+          ...(Object.keys(meta).length ? { meta } : {}),
+          ...(opts.dryRun ? { dryRun: true } : {})
+        },
+
+        result = await c.post('/jobs', spec);
+      if (opts.json){
+        console.log(JSON.stringify(result));
+      }
+      else {
+        console.log(`Job ${result.jobId} queued`);
+      }
+
+      if (opts.detach){
+        return process.exit(0);
+      }
+
+      const code = await followJob(c, result.jobId, { waitMode: opts.wait });
+      process.exit(code);
+    }
+    catch (err){
+      fail(err);
+    }
+  });
+
+program
+  .command('status')
+  .description('Show status; follow log if running, show artifacts if done')
+  .argument('<jobId>')
+  .option('--json', 'Machine-readable output', false)
+  .action(async (jobId, opts) => {
+    try {
+      const c = client(),
+        job = await c.get(`/jobs/${jobId}`);
+      if (opts.json && !ACTIVE_JOB_STATES.has(job.state)){
+        console.log(JSON.stringify(job));
+        return process.exit(exitCodeForJobState(job.state));
+      }
+
+      console.log(`Job ${job.id} — ${job.state}${job.resource ? ' on ' + job.resource.name : ''}`);
+      console.log(`Created: ${job.created_at}`);
+
+      if (ACTIVE_JOB_STATES.has(job.state)){
+        const code = await followJob(c, jobId, { fromSeq: 0, waitMode: false });
+        return process.exit(code);
+      }
+
+      const { artifacts } = await c.get(`/jobs/${jobId}/artifacts`);
+      console.log(`Verdict: ${job.state}`);
+      for (const a of artifacts){
+        console.log(`  ${a.name}  ${a.url}`);
+      }
+      process.exit(exitCodeForJobState(job.state));
+    }
+    catch (err){
+      fail(err);
+    }
+  });
+
+program
+  .command('cancel')
+  .description('Cancel a job')
+  .argument('<jobId>')
+  .action(async (jobId) => {
+    try {
+      const job = await client().post(`/jobs/${jobId}/cancel`);
+      console.log(`Job ${job.id} -> ${job.state}`);
+    }
+    catch (err){
+      fail(err);
+    }
+  });
+
+program
+  .command('resources')
+  .description('List resources and their status')
+  .option('--json', 'Machine-readable output', false)
+  .action(async (opts) => {
+    try {
+      const { resources } = await client().get('/resources');
+      if (opts.json){
+        return console.log(JSON.stringify(resources));
+      }
+      printTable(resources, [
+        ['NAME', (r) => r.name],
+        ['TYPE', (r) => r.type],
+        ['STATUS', (r) => r.status],
+        ['BUSY', (r) => r.busySource || '-'],
+        ['LABELS', (r) => r.labels.join(',')],
+        ['LAST HEARTBEAT', (r) => r.lastHeartbeatAt || 'never']
+      ]);
+    }
+    catch (err){
+      fail(err);
+    }
+  });
+
+program
+  .command('jobs')
+  .description('List recent jobs')
+  .option('--mine', 'Only jobs submitted by this agent token', false)
+  .option('--state <state>', 'Filter by state')
+  .option('--json', 'Machine-readable output', false)
+  .action(async (opts) => {
+    try {
+      const { jobs } = await client().get('/jobs', { query: { mine: opts.mine, state: opts.state } });
+      if (opts.json){
+        return console.log(JSON.stringify(jobs));
+      }
+      printTable(jobs, [
+        ['ID', (j) => j.id],
+        ['SOURCE', (j) => j.source],
+        ['USER', (j) => j.spec.user || '-'],
+        ['STATE', (j) => j.state],
+        ['CREATED', (j) => j.created_at]
+      ]);
+    }
+    catch (err){
+      fail(err);
+    }
+  });
+
+const config = program.command('config').description('Manage local Agent configuration');
+config
+  .command('set')
+  .argument('<key>', 'url | token | group | user')
+  .argument('<value>')
+  .action((key, value) => {
+    if (!['url', 'token', 'group', 'user'].includes(key)){
+      console.error('Error: key must be "url", "token", "group", or "user"');
+      process.exit(EXIT_CODES.USAGE);
+    }
+    const current = readConfigFile();
+    writeConfigFile({ ...current, [key]: value });
+    console.log(`Saved ${key} to config`);
+  });
+
+function collectRepeatable(value, previous){
+  return [...previous, value];
+}
+
+function printTable(rows, columns){
+  if (rows.length === 0){
+    console.log('(none)');
+    return;
+  }
+  const widths = columns.map(([header], i) => Math.max(header.length, ...rows.map((r) => String(columns[i][1](r)).length))),
+    line = (cells) => cells.map((c, i) => String(c).padEnd(widths[i])).join('  ');
+  console.log(line(columns.map(([h]) => h)));
+  for (const row of rows){
+    console.log(line(columns.map(([, f]) => f(row))));
+  }
+}
+
+program.parseAsync(process.argv);

package/src/config.js

@@ -0,0 +1,79 @@
+/**
+ * @file        packages/agent/src/config.js
+ * @description Agent config resolution: flags > env > config file > bundled default (url/token/group/user)
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const fs = require('node:fs'),
+  os = require('node:os'),
+  path = require('node:path');
+
+// §7: "Configuration is read from flags, then environment (THUB_URL,
+// THUB_TOKEN), then ~/.config/thub/config.json."
+const CONFIG_PATH = path.join(os.homedir(), '.config', 'thub', 'config.json'),
+
+  // Bundled with the package as a last-resort default, below the user's own
+  // config file, so `thub` has something to fall back on before `config set`
+  // has ever been run.
+  PACKAGE_DEFAULT_CONFIG_PATH = path.join(__dirname, '..', 'config.json');
+
+function readJsonFile(filePath){
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  }
+  catch {
+    return {};
+  }
+}
+
+function readConfigFile(){
+  return readJsonFile(CONFIG_PATH);
+}
+
+function writeConfigFile(config){
+  fs.mkdirSync(path.dirname(CONFIG_PATH), { recursive: true });
+  fs.writeFileSync(CONFIG_PATH, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+}
+
+function resolveConnection(flags = {}){
+  const file = { ...readJsonFile(PACKAGE_DEFAULT_CONFIG_PATH), ...readConfigFile() },
+    url = flags.url || process.env.THUB_URL || file.url,
+    token = flags.token || process.env.THUB_TOKEN || file.token;
+  if (!url || !token){
+    const err = new Error(
+      'Missing coordinator URL or token. Set with `thub config set url <url>` / `thub config set token <token>`, ' +
+        'or THUB_URL / THUB_TOKEN, or --url / --token.'
+    );
+    err.status = 4;
+    throw err;
+  }
+  return { url, token };
+}
+
+// Optional default for `--group` (§4.3/§7.1) — same flags > env > file
+// precedence as url/token, but unset is fine: a job just runs unconstrained
+// by group, same as if `groups` had never been used at all.
+function resolveGroup(flags = {}){
+  const file = { ...readJsonFile(PACKAGE_DEFAULT_CONFIG_PATH), ...readConfigFile() };
+  return flags.group || process.env.THUB_GROUP || file.group || undefined;
+}
+
+// Optional default for `--user` (§4.3/§7.1) — same flags > env > file
+// precedence as group. Purely a label (who submitted this job), not an
+// identity: unset is fine, and nothing on the Coordinator side enforces
+// or authenticates it.
+function resolveUser(flags = {}){
+  const file = { ...readJsonFile(PACKAGE_DEFAULT_CONFIG_PATH), ...readConfigFile() };
+  return flags.user || process.env.THUB_USER || file.user || undefined;
+}
+
+module.exports = { CONFIG_PATH, readConfigFile, writeConfigFile, resolveConnection, resolveGroup, resolveUser };

package/src/duration.js

@@ -0,0 +1,33 @@
+/**
+ * @file        packages/agent/src/duration.js
+ * @description Parses human-readable durations (e.g. 30m, 1h) into seconds
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const UNITS = { s: 1, m: 60, h: 3600, d: 86400 };
+
+function parseDurationSec(input){
+  if (input === undefined){
+    return undefined;
+  }
+  if (typeof input === 'number'){
+    return input;
+  }
+  const match = /^(\d+)([smhd])?$/.exec(String(input).trim());
+  if (!match){
+    throw new Error(`Invalid duration "${input}" — use e.g. 30m, 1h, 900s`);
+  }
+  const [, n, unit] = match;
+  return Number(n) * (UNITS[unit] || 1);
+}
+
+module.exports = { parseDurationSec };

package/src/streaming.js

@@ -0,0 +1,118 @@
+/**
+ * @file        packages/agent/src/streaming.js
+ * @description Follows a job's live log stream and resolves the CLI's exit code
+ *
+ * @author      Andrian Yablonskyy
+ * @copyright   Copyright (c) 2026 Andrian Yablonskyy. All rights reserved.
+ *
+ * This file is part of TestHub and is proprietary and confidential.
+ * Unauthorized copying, modification, distribution, or use of this file,
+ * via any medium, is strictly prohibited without prior written permission
+ * from AdSystem.PRO.
+ */
+
+'use strict';
+
+const { exitCodeForJobState, EXIT_CODES } = require('@andrian.yablonskyy/thub-common');
+
+/**
+ * Streams a job's logs until it reaches a terminal state, or the user
+ * hits Ctrl-C. Reconnects with exponential backoff and resumes from the
+ * last seen `seq` on network drops (§7).
+ *
+ * In --wait mode (used by CI, §11) Ctrl-C/SIGINT is treated as a cancel
+ * request; otherwise it only detaches and the job keeps running.
+ */
+async function followJob(client, jobId, { fromSeq = 0, waitMode = false, print = console.log } = {}){
+  let lastEventId = fromSeq,
+    finished = false,
+    backoffMs = 500;
+  const controller = new AbortController(),
+
+    onSigint = async () => {
+      if (finished){
+        return;
+      }
+      finished = true;
+      controller.abort();
+      if (waitMode){
+        print('\nReceived cancel signal — canceling job...');
+        try {
+          await client.post(`/jobs/${jobId}/cancel`);
+        }
+        catch {
+        // best effort — the process is exiting either way
+        }
+        resolveOnce(EXIT_CODES.CANCELED);
+      }
+      else {
+        print(`\nDetached. Job keeps running.\nthub status ${jobId}`);
+        resolveOnce(EXIT_CODES.DETACHED);
+      }
+    };
+
+  let resolveOnce;
+  const done = new Promise((resolve) => {
+    resolveOnce = (code) => {
+      finished = true;
+      resolve(code);
+    };
+  });
+
+  process.on('SIGINT', onSigint);
+
+  (async () => {
+    while (!finished){
+      try {
+        await client.streamEvents(`/jobs/${jobId}/logs/stream`, {
+          lastEventId,
+          signal: controller.signal,
+          onEvent: ({ event, id, data }) => {
+            if (id){
+              lastEventId = id;
+            }
+            if (event === 'log'){
+              print(`[${data.stream}] ${data.line}`);
+            }
+            else if (event === 'state'){
+              print(`-- ${data.state}${data.resource ? ' on ' + data.resource : ''} --`);
+            }
+            else if (event === 'end'){
+              print(`\nJob finished: ${data.state}`);
+              if (data.artifactsUrl){
+                print(`Artifacts: ${data.artifactsUrl}`);
+              }
+              resolveOnce(exitCodeForJobState(data.state));
+            }
+          }
+        });
+        if (!finished){
+          // Server closed the stream without an `end` event (rare) — retry.
+          await sleep(backoffMs);
+          backoffMs = Math.min(backoffMs * 2, 10_000);
+        }
+      }
+      catch {
+        if (controller.signal.aborted){
+          break;
+        }
+        await sleep(backoffMs);
+        backoffMs = Math.min(backoffMs * 2, 10_000);
+      }
+    }
+  })();
+
+  try {
+    return await done;
+  }
+  finally {
+    process.off('SIGINT', onSigint);
+    controller.abort();
+  }
+}
+
+function sleep(ms){
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+module.exports = { followJob };