instar 0.5.0 → 0.6.0

package/dist/core/StateManager.d.ts

@@ -26,6 +26,7 @@ export declare class StateManager {
     }): ActivityEvent[];
     get<T>(key: string): T | null;
     set<T>(key: string, value: T): void;
+    delete(key: string): boolean;
     /**
      * Write a file atomically — write to .tmp then rename.
      * Prevents corruption from power loss or disk-full mid-write.

package/dist/core/StateManager.js

@@ -143,6 +143,19 @@ export class StateManager {
         fs.mkdirSync(dir, { recursive: true });
         this.atomicWrite(filePath, JSON.stringify(value, null, 2));
     }
+    delete(key) {
+        this.validateKey(key, 'state key');
+        const filePath = path.join(this.stateDir, 'state', `${key}.json`);
+        if (!fs.existsSync(filePath))
+            return false;
+        try {
+            fs.unlinkSync(filePath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
     /**
      * Write a file atomically — write to .tmp then rename.
      * Prevents corruption from power loss or disk-full mid-write.

package/dist/core/types.d.ts

@@ -61,6 +61,18 @@ export interface JobDefinition {
     tags?: string[];
     /** Telegram topic ID this job reports to (auto-created if not set) */
     topicId?: number;
+    /** Grounding configuration — what context this job needs at session start */
+    grounding?: JobGrounding;
+}
+export interface JobGrounding {
+    /** Whether this job requires identity grounding before execution */
+    requiresIdentity: boolean;
+    /** Whether this job processes external/untrusted input (requires security screening) */
+    processesExternalInput?: boolean;
+    /** Additional context files to inject at job start (relative to .instar/) */
+    contextFiles?: string[];
+    /** Custom grounding questions the agent must answer before proceeding */
+    questions?: string[];
 }
 export type JobPriority = 'critical' | 'high' | 'medium' | 'low';
 export interface JobExecution {

package/dist/publishing/TelegraphService.d.ts

@@ -5,6 +5,11 @@
  * content via the Telegraph API (telegra.ph). Zero-config,
  * no rate limits, instant web pages accessible from anywhere.
  *
+ * IMPORTANT: All Telegraph pages are PUBLIC. There is no authentication
+ * or access control — anyone with the URL can view the content.
+ * Do NOT publish sensitive, private, or confidential information.
+ * For private content, use the Cloudflare Tunnel viewer (when configured).
+ *
  * Telegraph API docs: https://telegra.ph/api
  */
 /** Valid Telegraph element tags */
@@ -79,7 +84,11 @@ export declare class TelegraphService {
      */
     createAccount(shortName: string, authorName?: string): Promise<TelegraphAccount>;
     /**
-     * Publish markdown content as a Telegraph page.
+     * Publish markdown content as a PUBLIC Telegraph page.
+     *
+     * WARNING: The published page is publicly accessible to anyone with the URL.
+     * Do not publish sensitive or private information.
+     *
      * Returns the page URL and path.
      */
     publishPage(title: string, markdown: string): Promise<TelegraphPage>;

package/dist/publishing/TelegraphService.js

@@ -5,6 +5,11 @@
  * content via the Telegraph API (telegra.ph). Zero-config,
  * no rate limits, instant web pages accessible from anywhere.
  *
+ * IMPORTANT: All Telegraph pages are PUBLIC. There is no authentication
+ * or access control — anyone with the URL can view the content.
+ * Do NOT publish sensitive, private, or confidential information.
+ * For private content, use the Cloudflare Tunnel viewer (when configured).
+ *
  * Telegraph API docs: https://telegra.ph/api
  */
 import fs from 'node:fs';
@@ -51,7 +56,11 @@ export class TelegraphService {
     }
     // ── Publishing ─────────────────────────────────────────────────
     /**
-     * Publish markdown content as a Telegraph page.
+     * Publish markdown content as a PUBLIC Telegraph page.
+     *
+     * WARNING: The published page is publicly accessible to anyone with the URL.
+     * Do not publish sensitive or private information.
+     *
      * Returns the page URL and path.
      */
     async publishPage(title, markdown) {

package/dist/scaffold/templates.js

@@ -170,12 +170,12 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 **Relationships** — Track people I interact with.
 - List: \`curl http://localhost:${port}/relationships\`
 
-**Publishing** — Share content as web pages via Telegraph. Instant, zero-config, accessible from anywhere.
+**Publishing** — Share content as PUBLIC web pages via Telegraph. Instant, zero-config, accessible from anywhere.
 - Publish: \`curl -X POST http://localhost:${port}/publish -H 'Content-Type: application/json' -d '{"title":"Page Title","markdown":"# Content here"}'\`
 - List published: \`curl http://localhost:${port}/published\`
 - Edit: \`curl -X PUT http://localhost:${port}/publish/PAGE_PATH -H 'Content-Type: application/json' -d '{"title":"Updated","markdown":"# New content"}'\`
 
-When the user needs to view rendered markdown — reports, summaries, documentation — publish it and share the link. The URL works on any device, no server tunnel required.
+**⚠ CRITICAL: All Telegraph pages are PUBLIC.** Anyone with the URL can view the content. There is no authentication or access control. NEVER publish sensitive, private, or confidential information through Telegraph. When sharing a link, always inform the user that the page is publicly accessible.
 
 **Scripts** — Reusable capabilities in \`.claude/scripts/\`.
 

package/dist/scheduler/JobLoader.d.ts

@@ -3,6 +3,11 @@
  *
  * Jobs define recurring work the agent should perform:
  * email checks, health probes, content publishing, etc.
+ *
+ * Grounding-by-default: Jobs are validated for grounding configuration.
+ * Missing grounding emits warnings — nudging the practice without breaking
+ * existing jobs. Jobs that process external input WITHOUT grounding get
+ * louder warnings because they represent a security surface.
  */
 import type { JobDefinition } from '../core/types.js';
 /**

package/dist/scheduler/JobLoader.js

@@ -3,11 +3,23 @@
  *
  * Jobs define recurring work the agent should perform:
  * email checks, health probes, content publishing, etc.
+ *
+ * Grounding-by-default: Jobs are validated for grounding configuration.
+ * Missing grounding emits warnings — nudging the practice without breaking
+ * existing jobs. Jobs that process external input WITHOUT grounding get
+ * louder warnings because they represent a security surface.
  */
 import fs from 'node:fs';
 import { Cron } from 'croner';
 const VALID_PRIORITIES = ['critical', 'high', 'medium', 'low'];
 const VALID_MODELS = ['opus', 'sonnet', 'haiku'];
+/** Slugs for lightweight default jobs where grounding is unnecessary. */
+const GROUNDING_EXEMPT_SLUGS = new Set([
+    'health-check',
+    'feedback-retry',
+    'dispatch-check',
+    'update-check',
+]);
 /**
  * Load and validate job definitions from a JSON file.
  * Throws on invalid structure — fail loud at startup, not at runtime.
@@ -26,10 +38,13 @@ export function loadJobs(jobsFile) {
     if (!Array.isArray(raw)) {
         throw new Error(`Jobs file must contain a JSON array, got ${typeof raw}`);
     }
-    return raw.map((job, index) => {
+    const jobs = raw.map((job, index) => {
         validateJob(job, index);
         return job;
     });
+    // Grounding-by-default audit — warn about jobs missing grounding config
+    auditGrounding(jobs);
+    return jobs;
 }
 /**
  * Validate a single job definition.
@@ -86,5 +101,66 @@ export function validateJob(job, index) {
     if (exec.args !== undefined && typeof exec.args !== 'string') {
         throw new Error(`${prefix}: execute.args must be a string if provided, got ${typeof exec.args}`);
     }
+    // Grounding config — validate structure if present
+    if (j.grounding !== undefined) {
+        validateGrounding(j.grounding, prefix);
+    }
+}
+/**
+ * Validate grounding configuration structure.
+ * Throws on invalid structure — if you're going to declare grounding, do it right.
+ */
+function validateGrounding(grounding, prefix) {
+    if (!grounding || typeof grounding !== 'object') {
+        throw new Error(`${prefix}: "grounding" must be an object if provided`);
+    }
+    const g = grounding;
+    if (typeof g.requiresIdentity !== 'boolean') {
+        throw new Error(`${prefix}: grounding.requiresIdentity must be a boolean`);
+    }
+    if (g.processesExternalInput !== undefined && typeof g.processesExternalInput !== 'boolean') {
+        throw new Error(`${prefix}: grounding.processesExternalInput must be a boolean if provided`);
+    }
+    if (g.contextFiles !== undefined) {
+        if (!Array.isArray(g.contextFiles)) {
+            throw new Error(`${prefix}: grounding.contextFiles must be an array of strings if provided`);
+        }
+        for (const f of g.contextFiles) {
+            if (typeof f !== 'string' || !f.trim()) {
+                throw new Error(`${prefix}: grounding.contextFiles entries must be non-empty strings`);
+            }
+        }
+    }
+    if (g.questions !== undefined) {
+        if (!Array.isArray(g.questions)) {
+            throw new Error(`${prefix}: grounding.questions must be an array of strings if provided`);
+        }
+        for (const q of g.questions) {
+            if (typeof q !== 'string' || !q.trim()) {
+                throw new Error(`${prefix}: grounding.questions entries must be non-empty strings`);
+            }
+        }
+    }
+}
+/**
+ * Audit loaded jobs for grounding configuration.
+ * Emits warnings for jobs missing grounding — the "nudge" layer.
+ * Exempt jobs (health-check, dispatch-check, etc.) are skipped silently.
+ */
+function auditGrounding(jobs) {
+    const ungrounded = [];
+    for (const job of jobs) {
+        if (!job.enabled)
+            continue;
+        if (GROUNDING_EXEMPT_SLUGS.has(job.slug))
+            continue;
+        if (!job.grounding) {
+            ungrounded.push(job.slug);
+        }
+    }
+    if (ungrounded.length > 0) {
+        console.warn(`[JobLoader] Grounding audit: ${ungrounded.length} enabled job(s) lack grounding config: ${ungrounded.join(', ')}. ` +
+            `Add a "grounding" field to declare identity and security requirements.`);
+    }
 }
 //# sourceMappingURL=JobLoader.js.map

package/dist/scheduler/JobScheduler.js

@@ -212,6 +212,18 @@ export class JobScheduler {
     spawnJobSession(job, reason) {
         const prompt = this.buildPrompt(job);
         const sessionName = `job-${job.slug}-${Date.now().toString(36)}`;
+        // Write active-job.json BEFORE spawning so the session-start and
+        // compaction-recovery hooks can inject job-specific grounding context.
+        this.state.set('active-job', {
+            slug: job.slug,
+            name: job.name,
+            description: job.description,
+            priority: job.priority,
+            sessionName,
+            triggeredBy: reason,
+            startedAt: new Date().toISOString(),
+            grounding: job.grounding ?? null,
+        });
         this.sessionManager.spawnSession({
             name: sessionName,
             prompt,
@@ -285,6 +297,11 @@ export class JobScheduler {
         const job = this.jobs.find(j => j.slug === session.jobSlug);
         if (!job)
             return;
+        // Clear active-job.json now that the job is done
+        const activeJob = this.state.get('active-job');
+        if (activeJob?.slug === job.slug) {
+            this.state.delete('active-job');
+        }
         // Update job state with completion result
         const failed = session.status === 'failed' || session.status === 'killed';
         const existingState = this.state.getJobState(job.slug);

package/dist/server/routes.js

@@ -820,7 +820,10 @@ export function createRoutes(ctx) {
         }
         try {
             const page = await ctx.publisher.publishPage(title, markdown);
-            res.status(201).json(page);
+            res.status(201).json({
+                ...page,
+                warning: 'This page is PUBLIC. Anyone with the URL can view it.',
+            });
         }
         catch (err) {
             res.status(500).json({ error: err instanceof Error ? err.message : String(err) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Persistent autonomy infrastructure for AI agents",
   "type": "module",
   "main": "dist/index.js",