DEV Community: Gaurang

Your AI Agent Needs a Brake Pedal: Approval Gates, Scoped Permissions and Dry Runs

Gaurang — Tue, 29 Sep 2026 04:49:02 +0000

Agents are no longer only answering questions. They open PRs, run queries and send emails. Developer forums and regulators are now openly asking who is responsible when an agent does something nobody approved.

Whatever the answer turns out to be, the engineering answer is the same: give real capability, but bound the blast radius. Three patterns do most of that work.

1. Approval gates: the agent proposes, a human decides

The agent still reasons and plans. For consequential tools, the final "actually do it" step waits for a person.

async function runAgentLoopWithApproval(goal, tools, consequentialTools,
                                        callModel, requestHumanApproval) {
  const observations = [];
  for (let step = 1; step <= 8; step++) {
    const decision = await callModel({ goal, observations });
    if (decision.type === "final_answer") return decision.content;

    if (consequentialTools.includes(decision.tool)) {
      const approved = await requestHumanApproval(decision); // blocks
      if (!approved) {
        observations.push({ step, tool: decision.tool,
                            result: { rejected: true, reason: "not approved" } });
        continue; // the agent sees the rejection and re-plans
      }
    }

    const result = await tools[decision.tool](decision.arguments);
    observations.push({ step, tool: decision.tool, result });
  }
}

Don't gate everything. An agent that asks permission for every search is slower than doing the task yourself. Gate the tools that send, write, delete or spend.

2. Scoped permissions: make the bad action impossible

A gate depends on a human noticing a bad proposal. A scoped permission means the bad action was never possible in the first place.

A support agent's DB tool can only SELECT this customer's rows. No DELETE, no other customers.
A deploy agent's token can deploy to staging, not production.

This is plain least privilege, and it's also the strongest defense against prompt injection, because an injected instruction can't call a capability the agent doesn't have.

3. Dry runs: show the effect before committing

A dry run executes the planning logic without the side effect:

"This would delete 3 rows: id IN (812, 813, 977)."

A gate asks should this happen? A dry run answers what exactly would happen? They work best together. Approving a concrete dry-run result is far more meaningful than approving "delete some records."

Choosing the combination

Action	Example	Guardrail
Low stakes, reversible	search, read-only lookup	none needed
Moderate, harder to reverse	email a customer, update a record	approval gate + dry run
High stakes, irreversible	payments, prod data deletion	scoped permissions and gate. Never the gate alone

These are the direct mitigations for "Excessive Agency" in the OWASP Top 10 for LLM applications. It's the risk that grows fastest as agents get more capable.

This is from the AI/LLM Engineering pillar on discoveringCode, a free, ad-free notebook that goes from beginner to expert on AI/LLM engineering and four other pillars. Related: why prompt injection can't simply be patched.

PDF Toolkit Where Your Files Can't Leave the Browser (and the CSP Enforces It)

Gaurang — Sun, 27 Sep 2026 07:20:20 +0000

Think about the last time you merged two PDFs online. You dragged a bank statement, a lease or a scan of your passport into a website, it "processed" the file, and you downloaded the result. Where did the file go in between? Usually it went to someone else's server, and all you have is their word that they deleted it.

I wanted a tool where that question has a boring answer, so I built Dokwise: 16 PDF and image tools (merge, split, compress, OCR, protect, compare, scan-to-PDF, e-signature and more) that run entirely in your browser. There's no backend and no account, and after the first load it works offline.

"We don't upload your files" is easy to say, though, and plenty of sites that say it are wrong. This post covers how Dokwise backs the claim up.

1. There is no server to upload to

Dokwise is a static site. There's no API and no file-processing server. You can't accidentally send a file to a backend that doesn't exist.

The processing runs on libraries that work in the browser:

Job	Library
Create / merge / split / edit PDFs	`pdf-lib`
Render, rasterize, extract text	`pdfjs-dist`
Image resize / compress / convert	Canvas + `OffscreenCanvas`
OCR	`tesseract.js` (WASM)
AES-256 PDF encryption	`@pdfsmaller/pdf-encrypt` on top of native `crypto.subtle`

2. Heavy work runs in Web Workers and reports progress

Each tool is a plain config object with a process() function. The shell UI (drop zone, options, progress bar, download) is shared, so a new tool is just a config plus a worker. The worker receives ArrayBuffers, does its job, and transfers the result back rather than copying it:

self.onmessage = async (event: MessageEvent<MergeRequest>) => {
  const { type, files } = event.data;
  if (type !== 'merge') return;

  const bytes = await mergePdfs(
    files.map((f) => ({ name: f.name, bytes: new Uint8Array(f.buffer) })),
  );
  const buffer = new ArrayBuffer(bytes.byteLength);
  new Uint8Array(buffer).set(bytes);
  self.postMessage({ type: 'success', buffer }, { transfer: [buffer] });
};

Any operation that can take more than a second has to post { type: 'progress', percent }. That's a hard rule in the project. Compressing a 200-page PDF on a phone shouldn't mean staring at a spinner and wondering whether the tab has frozen.

3. The CSP turns the promise into an enforced rule

This is the part I care most about. The production build injects a strict Content-Security-Policy:

default-src 'self';
script-src 'self' https://www.googletagmanager.com;
connect-src 'self' https://www.googletagmanager.com
            https://*.google-analytics.com https://*.analytics.google.com;
img-src 'self' data: blob:;
worker-src 'self' blob:;
object-src 'none';
frame-src 'none';

Every fetch, XHR or WebSocket to a host that isn't listed gets blocked by the browser. It doesn't matter if the call comes from my code or from a dependency buried in node_modules. If a library quietly tries to phone home, it fails loudly instead of shipping silently.

Being honest about it: the only third-party hosts on that list belong to Google Analytics, which gets anonymous page views. It never receives file contents or filenames. It's disclosed on the site's privacy page, and you can see it in the CSP above.

Don't trust me, check it: open DevTools → Network, run any tool, and watch what goes out. Your file won't be in there.

4. The OCR problem: tesseract.js calls a CDN by default

The CSP caught a real problem here. Out of the box, tesseract.js downloads its worker script, WASM core and language data from a CDN at runtime. That's a third-party network call in the middle of processing your document, which is exactly what I'm trying to avoid.

The fix was to vendor all of it (~30 MB) and point tesseract at same-origin paths:

const worker = await Tesseract.createWorker('eng', Tesseract.OEM.LSTM_ONLY, {
  workerPath: '/tessdata/worker.min.js',
  corePath: '/tessdata/core',
  langPath: '/tessdata',
  gzip: true,
});

So nobody pays 30 MB on every visit, the PWA service worker leaves tessdata/ out of the install-time precache and caches it the first time you actually run OCR. After that, OCR works offline too.

What you can do with it today

✅ Merge, split, organize (rotate / reorder / delete / crop pages)
✅ Compress PDFs and images, convert JPG / PNG / WebP / HEIC
✅ OCR scanned PDFs into searchable ones
✅ Protect with AES-256, remove a password you know, strip metadata
✅ Word ↔ PDF, compare two PDFs as a redline, repair broken PDFs
✅ Scan to PDF with your camera, clean up a signature photo into a transparent PNG
✅ Install it as a PWA and use it on a plane

Try it at dokwise.in. I'd really like feedback from people who poke at it with DevTools open. If you spot a request that shouldn't be there, tell me.

Built with React, Vite, TypeScript, pdf-lib, pdfjs-dist and tesseract.js. The privacy page, with the full CSP and a DevTools walkthrough, is at dokwise.in/privacy.

How a One-Line Column Rename Takes Down Production (and the Expand/Contract Fix)

Gaurang — Sun, 27 Sep 2026 07:02:49 +0000

Deploying new app code is the easy half. A rolling deploy swaps instances a few at a time, and for a few minutes old and new versions serve traffic side by side. That's fine; they're stateless.

The hard half starts when the deploy also changes the database schema. For those same minutes, both versions have to run correct queries against the same database.

The one-liner that breaks things

ALTER TABLE users RENAME COLUMN email TO email_address;

It looks trivial. But mid-deploy:

Old instances still run SELECT email FROM users.
New instances already use email_address.

The moment the migration runs, every request hitting an old instance fails with column "email" does not exist. That's a real outage, even though the code on each side is correct on its own.

The fix: expand/contract

Don't require the schema to be right at one single instant. Split one risky change into several safe ones, each compatible with both live versions.

Stage 1: Expand. Add the new column, nullable:

ALTER TABLE users ADD COLUMN email_address TEXT; -- no default, no table rewrite

Old code doesn't know it exists, and nothing breaks.

Stage 2: Dual-write. Deploy code that writes both columns but still reads the old one:

await pool.query(
  `INSERT INTO users (name, email, email_address)
   VALUES ($1, $2, $2) RETURNING id, name, email`,
  [name, email],
);

Stage 3: Backfill. Copy old rows in batches, not one giant UPDATE:

UPDATE users SET email_address = email
WHERE email_address IS NULL AND id BETWEEN 1 AND 10000;
-- repeat per batch until none remain

Stage 4: Switch reads. Once every row has email_address, deploy code that reads (and writes) only the new column.

Stage 5: Contract. Once every instance is on that version:

ALTER TABLE users DROP COLUMN email;

That's five steps instead of one RENAME, and at no point is live code running a query the schema can't answer.

The details that matter

The one rule: never require the schema and the live code to change at the same instant.
Batch your backfills. One huge UPDATE holds locks and floods the write-ahead log for its whole duration. Small batches take longer overall but don't compete with real traffic.
Dual-write is your rollback insurance. If stage 4 goes wrong, rolling back to the stage-2 or stage-3 version still works, because it never stopped writing the old column.
Not every change needs all five stages. A purely additive optional column is just stage 1. Save the full pattern for renames, type changes, column splits, or anything live code still depends on.

This is the closing topic of the Infra & Delivery pillar on discoveringCode, a free, ad-free notebook that goes from SSH-ing into a box by hand to containerized CI/CD. Related: deployment strategies: blue-green, canary, rolling.

"How Many Servers Do We Need?" — Back-of-the-Envelope Estimation for System Design

Gaurang — Sun, 20 Sep 2026 05:07:06 +0000

"How many servers do we need?" sounds like a question that needs a research project to answer. It doesn't — it needs five minutes of napkin math.

Back-of-the-envelope estimation is the habit of turning vague requirements ("we'll have a lot of users") into concrete numbers (queries per second, gigabytes of storage, megabits of bandwidth) before you design anything, because every real decision downstream — one database or many, a cache or not, which scaling strategy — depends on roughly knowing the size of the problem first.

The point is never precision. Nobody expects an exact server count from a five-minute calculation. The point is the right order of magnitude — knowing whether you're building for 100 requests a second or 100,000 completely changes the architecture, and that distinction is visible from rough math alone.

A worked example

A link-sharing app, 10 million daily active users

users posting a link:        1% of DAU post per day  = 100,000 posts/day
average post size:           ~1 KB (link + metadata)
daily write volume:          100,000 × 1KB            = ~100 MB/day
write QPS (spread evenly):   100,000 / 86,400 sec      ≈ 1.2 writes/sec
                                                          (but real traffic
                                                           isn't even — peak
                                                           is often 3-5x avg)
peak write QPS:               ~1.2 × 4                 ≈ 5 writes/sec

reads (10:1 read:write ratio, typical for social content):
peak read QPS:                 5 × 10                  ≈ 50 reads/sec

storage for 5 years of posts: 100 MB/day × 365 × 5     ≈ 180 GB
                                                          (comfortably fits
                                                          on one database)

Fifty reads a second and a couple hundred gigabytes of data is a completely different design conversation than fifty thousand reads a second and a couple hundred terabytes — and that difference took one minute of multiplication to surface.

Reference numbers worth memorizing

A handful of reference numbers make this fast:

A single reasonably-sized application server can typically handle somewhere from a few hundred to a few thousand requests per second, depending heavily on what each request does — simple reads land higher, requests that hit a database or do real computation land lower.
A relational database on solid hardware handles thousands of simple queries per second.
A network round trip within the same data center costs roughly 0.5–1ms; a round trip across the country or across an ocean costs 50–150ms.

None of these need to be exact — knowing "a server handles low thousands of req/sec, not millions" is enough to sanity-check any estimate you produce.

A few rules that make this fast

Work in the right units, and convert only at the end. Traffic is usually easiest to reason about in requests per day (from a DAU number) and then converted to requests per second by dividing by 86,400 — but daily active users don't spread their activity evenly across 24 hours. Real traffic has a peak-to-average ratio, commonly somewhere around 2–5x during a system's busiest hour, and any capacity plan built only on the average QPS will fall over during the actual peak, which is precisely when it matters most.

Storage math almost always dominates in surprising ways. A feature that feels "small" per item — a 280-character post, a single log line — adds up fast at scale: a million events a day, each 1KB, is a gigabyte a day, 365GB a year, without a single image or video involved. This is usually the number that first forces a "do we need object storage for this" or "do we need to shard this table" conversation, well before raw request volume does.

Round aggressively. 10 million users, not 9.7 million. 1KB per post, not 847 bytes. The entire value of this exercise is speed and directional correctness — spending ten minutes getting a number precise to three significant figures defeats the purpose, when the actual decision only cares whether you're closer to a hundred, a hundred thousand, or a hundred million.

This estimate becomes the shared vocabulary for every trade-off later in a system design discussion. "Do we need to shard the database" is unanswerable in the abstract, but very answerable once you know you're expecting 50,000 writes/sec against a single table. "Do we need a CDN" is unanswerable in the abstract, but obvious once you know 80% of your users are outside the region your one server lives in.

This is one topic in the System Design pillar on discoveringCode — a free, ad-free notebook that goes beginner-to-expert on frontend, backend, system design, infra, and AI/LLM engineering. Next up in the pillar: Availability, Reliability & the Nines.

What an LLM Actually Is (and Isn't)

Gaurang — Fri, 18 Sep 2026 16:17:23 +0000

An LLM doesn't "know" that Paris is the capital of France the way a database row knows it. It doesn't understand your question, and it isn't reasoning before it answers.

Here's the one sentence that explains almost everything "weird" about how these models behave:

A large language model is a function that takes in some text and outputs a probability distribution over what token is most likely to come next. That's it.

It has seen so much text where "The capital of France is" is followed by "Paris" that "Paris" gets an overwhelmingly high probability in that spot. Ask it something its training data genuinely didn't cover well, and it still has to output something with high probability — which is the actual mechanism behind hallucination.

Next-token prediction, made concrete

Feed the model a sequence of tokens (words and word-pieces). The model outputs a probability for every token in its vocabulary being the next one. A sampling step picks one, appends it, and the whole thing runs again to predict the token after that — one token at a time, until it hits a stop token or a length limit.

Here's a wildly simplified stand-in for the mechanism (real models score tens of thousands of candidate tokens with a neural network; this hardcodes a tiny probability table just to make the shape of it visible):

const nextTokenProbabilities = {
  "The capital of France is": { Paris: 0.91, Lyon: 0.03, France: 0.02, "?": 0.01 },
  "2 + 2 =": { "4": 0.97, "5": 0.01, "22": 0.01 },
};

function predictNext(promptSoFar) {
  const distribution = nextTokenProbabilities[promptSoFar] ?? { "...": 1.0 };
  const [bestToken] = Object.entries(distribution).sort((a, b) => b[1] - a[1])[0];
  return bestToken;
}

console.log(predictNext("The capital of France is")); // "Paris" — highest probability, not "known fact"
console.log(predictNext("2 + 2 ="));                   // "4" — same mechanism, correct answer

Notice: nothing in this function checks an answer against reality. Both correct outputs came from the identical process — "what token has the highest probability given everything before it" — as any hallucinated output would. There's no separate "is this true" step. That's not a bug you patch; it's the architecture.

What this rules out

No understanding, no reasoning "before" answering, in the way those words imply for a person. The model isn't silently forming an opinion and then describing it — the text is the computation. It's also why chain-of-thought prompting works at all: forcing the model to generate intermediate reasoning tokens genuinely changes what gets predicted next, because each new token becomes part of what the next prediction conditions on.

No live knowledge of anything after its training cutoff, and no access to your data, by default. Ask a base model what today's date is, and it can't know. Closing that gap is the entire premise of retrieval (RAG) and tool calling.

No persistent memory between separate API calls. Every request is stateless — "remembering" a conversation is really "re-sending the whole conversation so far," which is exactly why context windows become a hard, practical constraint the moment a conversation runs long.

Keep this mental model — text in, next-token probabilities out, sampled and repeated — in mind for everything else: tokenization, context windows, hallucination, prompting techniques, and even why agents get stuck in loops all trace back to this one mechanism.

This is the opening topic of the AI/LLM Engineering pillar on discoveringCode — a free, ad-free notebook that goes beginner-to-expert on frontend, backend, system design, infra, and AI/LLM engineering, with live interactive code playgrounds. If this was useful, the next topic on tokenization builds directly on it.