Introducing a new way to review your PRs.

Read the announcement

mvanhorn / last30days-skill

AI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary

View on GitHub

21 documents · Updated Nov 20, 2026

docs / runtime-configuration-and-safety

Runtime configuration and safety

The Last30Days runtime gives one research skill a safe path in both a local machine and a hosted service. It resolves user configuration, selects available source access, keeps private inputs local when needed, and reports limits before or during a run. The package targets Python 3.12 or newer and has no runtime package dependencies, so portability depends on the host's Python runtime and configured source tools.

Runtime model

Execution modes

The runtime supports two main execution modes. Local mode runs the research engine and source access on the user's machine. Hosted mode sends the topic to a configured remote API and receives the finished report. The command surface stays the same so a host can switch modes through configuration rather than a different research workflow.

The following flow shows how runtime choices affect where research runs.

flowchart TD
    A[Research request] --> B[Resolve runtime configuration]
    B --> C{Hosted key and endpoint set?}
    C -->|No| D[Run local sources and local synthesis]
    C -->|Yes| E{Local corpus selected?}
    E -->|Yes| D
    E -->|No| F[Submit to hosted API and poll for report]
    D --> G[Render or save result locally]
    F --> G

Local mode can work without a reasoning provider by using the engine's local planning and source paths. Optional credentials and external commands expand source coverage. A configured local corpus always keeps the run local, even when hosted settings exist, because file-derived evidence must not cross the hosted boundary. The research execution page describes the research flow that consumes this runtime decision.

References: skills/…/last30days.py• L3226-3280 skills/…/hosted.py• L1-25 skills/…/SKILL.md• L531-536 pyproject.toml• L1-16

Hosted execution

Hosted mode activates only when both LAST30DAYS_API_KEY and LAST30DAYS_API_BASE are set. The endpoint has no built-in default and must use HTTPS, except for allowed loopback hosts. The runtime sends the topic, depth, and any selected audience register to the configured API, then polls the returned search until it completes or fails.

The API key is used only for request authorization. The hosted client does not print, log, or persist it. A clarification response stops the run before research starts, while authentication, credit, rate, and server errors become clear user-facing outcomes.

Hosted mode has narrower output support than local mode. The server response supports its raw JSON shape, while the versioned local agent profile needs a local Report. Freshness verification also remains a local-only operation.

References: skills/…/hosted.py• L1-29 skills/…/hosted.py• L63-104 skills/…/hosted.py• L128-186 skills/…/hosted.py• L339-407 skills/…/last30days.py• L3240-3280

Configuration sources

Configuration is resolved into one runtime view before source selection. Process environment values have the highest priority. Trusted project settings and the global user file provide persistent choices. macOS Keychain and pass(1) provide lower-priority credential sources so a user can keep secrets encrypted at rest. This order lets a session override saved settings without changing them.

The default library policy does not trust project configuration and does not read browser cookies. The command line enables narrower policies for normal research, setup, or safe inspection. A project file cannot grant trust to itself. Trust must come from the process environment, global user configuration, or an explicit command policy.

Configuration also controls source inclusion and exclusion, endpoint overrides, save locations, model choices, time limits, hosted behavior, and the proxy used by YouTube command paths. The runtime exposes YOUTUBE_PROXY and its YT_PROXY alias through the same layered configuration view. This proxy applies only to yt-dlp traffic and does not change other HTTP calls. The runtime reports the selected source of configuration without exposing secret values. Unexpanded host placeholders are treated as unset and are reported as a setup problem instead of being sent as credentials. Setup, credentials, and preflight explains how users create and validate these settings.

First-run setup checks the same runtime view that research uses. It can prepare keyless source tools and report optional tools without claiming that an installed binary is usable. Setup writes keys and setup markers with restrictive file permissions, preserves existing values by default, and supports explicit key replacement when the user asks to rotate a credential.

The loader also keeps configuration behavior consistent with common .env files. It accepts export KEY=value lines, handles inline comments and quoted values, and preserves explicit empty values for settings that use empty as a disable signal. A new configuration entry must still pass through the same source layering and safe reporting path.

References: skills/…/env.py• L98-165 skills/…/env.py• L209-317 skills/…/env.py• L320-480 skills/…/env.py• L497-958 skills/…/setup_wizard.py• L588-709 skills/…/last30days.py• L2591-2623 pyproject.toml• L1-16

Safety boundaries

Private input boundaries

The runtime treats browser sessions, credentials, and local corpus files as separate private inputs. Browser-cookie reads are off unless the user or configuration explicitly enables them. Safe inspection can show which browsers are planned without reading cookie values.

Local corpus evidence is an offline source. It is excluded from hosted requests and from public or agent exports by default. The user must opt in before corpus evidence enters the stable agent JSON export. Report saving and library publishing are separate local-write or network actions, so creating a local report does not publish it.

The permission preflight presents planned reads, writes, commands, credentials, source access, and endpoint overrides as a secret-free summary. It does not run research or write setup, configuration, or report files.

The setup path follows the same consent boundary. It does not scan browser sessions unless the caller gives explicit consent and the host policy allows discovery. On an official-only host it records that browser sessions were not read, while still allowing keyless tool setup to continue. Setup, credentials, and preflight describes the user-facing consent choices.

Browser access failures remain bounded. If an opted-in browser denies access to X cookies, the runtime keeps any usable partial result, reports the denied browser, and gives a manual-cookie or API-key recovery path instead of hiding the source failure.

References: skills/…/env.py• L398-416 skills/…/env.py• L640-650 skills/…/env.py• L993-1059 skills/…/env.py• L1083-1205 skills/…/permission_preflight.py• L54-147 skills/…/setup_wizard.py• L70-135 skills/…/last30days.py• L2952-2968 skills/…/SKILL.md• L2276-2288

Network boundaries

The HTTP layer is the common boundary for provider and hosted requests. It adds bounded timeouts, retry rules, rate-limit handling, DNS recovery, and an optional shared wall deadline. Keyless Reddit requests share a rate limiter and a per-run response memo so concurrent research does not create an avoidable request burst or repeat the same fetch.

Debug logs mask secret-shaped query values. Redirects that cross an origin do not carry authentication headers to the new origin. Offline HTTP and source-fixture recording removes credential fields and known secret values before writing exchanges. Fixture replay fails closed on an unrecorded request and checks that all recorded exchanges were consumed, so offline evaluation cannot silently reach the network or hide a changed request shape. Rate-limit and credit failures retain distinct outcomes so recovery can point to waiting or topping up rather than retrying authentication. The execution boundaries and HTTP access page covers this client boundary in more detail.

References: skills/…/http.py• L25-127 skills/…/http.py• L147-287 skills/…/http.py• L318-499 skills/…/http.py• L553-725 skills/…/http.py• L728-996 skills/…/http.py• L1061-1269

Process boundaries

Some sources need local command-line tools. The runtime starts each controlled command with captured output and a time limit. On supported systems, a timed-out command's process group is terminated so child processes do not continue after the research request ends.

The main command also tracks registered child processes for final cleanup. Dependency checks now test that a command on PATH can run, not only that its name resolves. They distinguish a missing command, an executable that is off PATH, a broken command, and a probe timeout. This distinction lets diagnostics recommend a PATH fix, install, or reinstall instead of treating every unavailable source as a credential problem. The execution boundaries and HTTP access page covers command and network limits in more detail.

References: skills/…/subproc.py• L30-59 skills/…/subproc.py• L61-110 skills/…/last30days.py• L56-83 skills/…/health.py• L75-116 skills/…/health.py• L368-459

Runtime gates and diagnostics

Permission preflight

--preflight is the safe view of what a run may touch. It combines resolved configuration with source diagnosis and shows planned local reads, local writes, external commands, credential presence, network sources, and active or ignored endpoint overrides.

The preflight contract reports presence rather than values. It marks an untrusted project file as ignored and makes browser-cookie mode explicit. Hosts can use its JSON form as a stable permission summary or its text form as a human check before research.

References: skills/…/permission_preflight.py• L54-147 skills/…/permission_preflight.py• L154-242 skills/…/last30days.py• L2952-2968

Health diagnostics

The diagnostic system answers two different questions: whether a source is ready before a run and what happened during a run. doctor combines dependency checks, backend predictions, configuration state, permission data, and recent run evidence. It keeps missing, off-PATH, broken, timed-out, credit, and other failed states distinct. It groups each source into working, unverified, not working, or could be on, while preserving the more specific status for repair advice.

Safe diagnosis is local-only. It does not read browser-cookie values and avoids live network checks where a local signal is enough. A live probe is bounded and isolated per source. One bad probe becomes an error record rather than hiding the status of all other sources. When no fresh run exists, the doctor checks only free or keyless sources and leaves credit-gated sources unverified. A fresh saved run can replace prediction with observed source outcomes, while --postmortem can inspect an older run. A short-lived cached report is used only when its shape, schema, age, and non-secret configuration fingerprint still match. Reporting a problem still exits successfully so the report and its repair advice reach the caller. Health diagnostics and recovery explains the operational states and recovery paths.

References: skills/…/doctor.py• L1-39 skills/…/doctor.py• L115-153 skills/…/doctor.py• L1189-1277 skills/…/doctor.py• L1479-1596 skills/…/doctor.py• L1600-1770 skills/…/doctor.py• L1793-2059 skills/…/env.py• L184-206 skills/…/pipeline.py• L1786-1880 skills/…/health.py• L23-50 skills/…/health.py• L368-459

Query safety gate

The runtime checks a small set of known low-signal query patterns before source retrieval. For a demographic shopping phrase without hobby, relationship, or budget context, it refuses to spend time on a likely poor search and asks for useful context instead.

This gate protects research quality rather than system access. An explicit skip setting can bypass it when the user accepts the risk. Source health still runs separately, so a valid query can produce a partial result when a provider is unavailable.

References: skills/…/preflight.py• L1-13 skills/…/preflight.py• L59-119 skills/…/last30days.py• L3334-3339

Change checklist

When these files or sections are changed, remember to consider these:

  • When changing the declared Python version or dependency set, verify that host setup paths and the runtime portability contract still match the supported environment.
  • When adding a credential, endpoint, or runtime flag, update configuration resolution, safe diagnosis, and the permission preflight view together. Otherwise the run may use a setting that the safety summary does not show.
  • When changing hosted request or response behavior, update the local/hosted selection gate, output-profile rules, and error handling as one contract.
  • When changing hosted endpoint validation, keep the HTTPS and loopback policy aligned with the mode-selection gate and the user-facing setup guidance.
  • When adding a browser-backed source, update the consent policy, plan-only inspection state, cookie-domain mapping, and privacy export rules together.
  • When changing an external command or its install path, keep PATH-based availability, dependency health states, timeout cleanup, and repair guidance aligned.
  • When changing local corpus or publishing behavior, verify that hosted bypass and export suppression still use the same privacy decision.
  • When changing HTTP retries, redirects, fixture recording, or source outcomes, keep the shared deadline, secret redaction, fail-closed replay, and recovery labels aligned.
  • When changing setup installation or key writes, keep engine visibility, off-PATH reporting, file permissions, and idempotent or explicit replacement behavior aligned.
  • When changing diagnostic cache inputs or report shape, keep the schema check, non-secret fingerprint, freshness rule, and live fallback aligned so stale health is never served as current.
  • When changing configuration loading, keep placeholder rejection, source precedence, and the secret-presence view aligned so a host cannot send an unresolved template or report it as a valid credential.
  • When changing browser-cookie extraction, keep the shared browser selection policy, consent state, denied-access reporting, and complete-session preference aligned across setup, diagnostics, and research.

Important failure modes

TriggerConsequenceGuard
The host uses Python older than 3.12The package cannot run under its declared runtime contract.Use Python 3.12 or newer before setup or execution.
Only one of LAST30DAYS_API_KEY or LAST30DAYS_API_BASE is setThe request runs locally instead of using the hosted service.Hosted mode requires both values and has no default endpoint.
The hosted endpoint uses HTTP for a non-loopback hostThe hosted request is rejected instead of using an insecure remote connection.Hosted endpoint validation requires HTTPS, with HTTP limited to allowed loopback hosts.
Hosted settings are present with a local corpusFile-derived evidence could cross the remote boundary if hosted mode won.The runtime bypasses hosted mode and runs locally.
Project configuration is not trustedThe project file and its endpoint or credential settings are ignored.Trust must come from the process environment, global configuration, or explicit command policy.
Browser cookies are enabled during safe inspectionA diagnostic could trigger a cookie read or a system credential prompt.doctor, --diagnose, and --preflight use plan-only cookie mode.
An opted-in browser denies X cookie accessX may remain unavailable even though browser access was requested.The runtime reports the denied browser and points to manual cookies or XAI_API_KEY.
A source command is missing, off PATH, broken, or hangsThe related source becomes unavailable or degraded.Dependency probes classify the state and subprocess execution cleans up timed-out process groups.
A setup installer succeeds but its binary is off PATHSetup reports success while the engine still cannot use the source.Setup verifies engine visibility and reports the installed path separately.
A cross-origin redirect carries an authorization headerA credential could be sent to an unintended host.The HTTP redirect boundary strips authentication headers when the origin changes.
Fixture recording or replay handles a secret or unrecorded request incorrectlyOffline artifacts can leak a credential or evaluation can reach the network.Recording scrubs secret names and values; replay rejects unrecorded and unused exchanges.
A 402 or credits-exhausted response is treated as an auth failureRecovery sends the user to log in again instead of adding credits.HTTP classification and health reporting preserve a payment-required outcome.
A hosted run requests the local agent JSON profileNo local Report exists to build that profile.The CLI rejects that profile and directs the caller to the hosted raw JSON contract.
A query matches the known demographic shopping trapRetrieval can consume time and return generic, low-signal material.The query gate refuses before pipeline work and asks for context.
A host passes an unexpanded ${user_config.name} valueThe placeholder can look like a credential and reach a provider as a bad secret.Configuration treats the value as unset, restores any valid lower-priority value, and reports the unresolved key.
A cached doctor report outlives a credential, host, backend, or opt-in changeDiagnostics can show yesterday's source state.The cache expires by time and by a fingerprint of non-secret configuration signals.
A live doctor probe checks a paid or session-gated sourceA health check could spend credits or trigger an auth limit.Doctor probes only free or keyless sources and leaves the gated sources unverified.

Key files

FileWhy to read it
skills/…/last30days.pyMain runtime gate for configuration policy, preflight, local or hosted selection, and child-process cleanup.
skills/…/env.pySource-of-truth view of configuration layering, trust policy, credential sources, placeholder handling, host policy, browser-cookie policy, and source-specific proxy settings.
skills/…/hosted.pyHosted API contract, endpoint validation, polling behavior, secret handling, and hosted error outcomes.
skills/…/pipeline.pySafe diagnosis contract and the link between runtime availability and selected sources.
skills/…/permission_preflight.pySecret-free permission object and human-readable preflight output.
skills/…/http.pyNetwork timeout, retry, deadline, redirect, rate-limit, fixture, memo, and redaction boundaries.
skills/…/subproc.pyControlled command execution and process-group cleanup.
skills/…/health.pyShared vocabulary for dependency health, off-PATH tools, and per-run source outcomes.
skills/…/doctor.pyAggregated operational health report, audit states, recent-run evidence, safe cache, and bounded probe model.
skills/…/setup_wizard.pyFirst-run consent, source-tool setup, off-PATH detection, and secret-safe configuration writes.
skills/…/preflight.pyQuery-quality refusal gate that runs before source retrieval.
skills/…/SKILL.mdHost-facing consent, privacy, setup, and runtime-use rules.
pyproject.tomlDeclared Python runtime, package dependency contract, and project test and coverage policy.