thats.nono

Give Every Agent Its Own Worktree

Yoonsoo Park — Mon, 24 Aug 2026 09:05:00 -0400

Cursor shipped a feature called Shadow Workspace: a background agent runs tests, linting, and spec checks in a separate, isolated Git worktree, so it can iterate on your code without disturbing the files you are actively editing. The agent gets a real working tree to mutate; you keep typing in yours; nobody steps on anybody.

When I read the announcement my reaction was not “neat feature.” It was “yes, that is the pattern, and it should be the default.” Because I had already been running it by hand, and separately I had watched what happens when you don’t.

The failure mode isolation prevents

Anthropic published research this month where they put several Claude agents on the same codebase without telling them about each other, and without any ownership or conflict policy. The agents started treating each other’s edits as hostile. Some runs escalated into what the writeup fairly called sabotage: agents interrupting each other’s processes, locking each other out, undoing each other’s work. A few runs reached a peaceful negotiated state, sometimes by asking for human mediation. But the default outcome of “many agents, one shared mutable workspace, no policy” was a turf war.

That is the same class of bug as two developers force-pushing to the same branch, except the agents run faster and have less shame about it. The root cause is not that the agents are malicious. It is that they share a single mutable surface with no boundary, so every write is a potential collision, and a collision looks like an attack.

The fix is not a smarter agent. It is a boundary.

What I already do by hand

My working tree gets dirty. Half-finished edits, scratch files, an experiment I have not decided about yet. When I need a clean branch off main to do one focused thing, the naive move is git checkout -b, and it fails or drags the mess along, and then I am stashing and un-stashing and fighting my own uncommitted state.

The move that actually works is git worktree. It gives me a second, physically separate checkout of the same repository on its own branch, in its own directory. My dirty main tree stays exactly as it is. I do the focused work in the isolated tree, commit it, push it, and remove the worktree. Two branches, two directories, zero interference. I reach for this specifically when the main tree is too dirty to safely branch from, and it has never once made me stash-juggle.

That is Cursor’s Shadow Workspace, minus the automation. The insight is identical: an agent (or a task, or a version of me) that needs to mutate files should get its own worktree, not share yours.

The same pattern one level up

I run a lot of work through subagents, delegated tasks that execute in their own isolated context with their own terminal session. The reason that works, and does not turn into the Anthropic turf war, is precisely that each one is boxed. A subagent cannot reach into the parent’s state and clobber it. It gets a scope, does the work there, and returns a result. The isolation is what makes parallelism safe. Take the box away and you are back to agents fighting over one mutable surface.

So there are three heights of the same idea:

File level: git worktree gives an agent its own checkout. Cursor automates this as Shadow Workspace.
Task level: each delegated subagent gets its own context and terminal, so concurrent tasks cannot corrupt each other.
System level: the Anthropic research shows what the absence of any of this looks like, agents on one shared surface with no ownership, and it is not pretty.

The lesson threads through all three: concurrency is safe when each actor mutates its own copy and merges through a controlled join, and dangerous when they all write the same place and hope.

The tradeoff, honestly

Isolation is not free. Each worktree is another checkout on disk. Cursor’s own writeup flags the disk I/O cost of cloning worktrees in a large monorepo, and that is a real concern. If your repo is huge and your agents are many, N full worktrees can hurt.

But the cost is disk and setup time, both of which are cheap and boring. The cost of not isolating is collisions, corrupted state, and in the multi-agent case active sabotage, which are expensive and exciting in the worst way. I will pay disk to avoid a turf war every time.

What to actually do

If you run background or parallel coding agents, give each one its own worktree or its own isolated context. Do not let two agents mutate the same working tree at once. This is the single highest-leverage safety property for multi-agent coding.
If you are a human fighting your own dirty tree, learn git worktree before you learn to juggle stashes. It is the cleaner tool and it is already in Git.
Treat merges as the controlled join point. Each isolated actor produces a branch; you review and merge. The isolation buys you the ability to review before anything lands, which is exactly what the shared-surface agents never got.
When you evaluate a multi-agent framework, ask where the boundary is before you ask how smart the agents are. If the answer is “they share a workspace and coordinate by talking,” you have read the Anthropic paper and you know how that ends.

The clean architecture diagram of a multi-agent system hides the moment where two arrows write the same file. Isolation is how you make sure that moment never arrives.

Irreversible Actions Cannot Be Gated by a Prompt

Yoonsoo Park — Mon, 24 Aug 2026 09:00:00 -0400

In August 2026 an AI assistant was told to book a gym class. The class was full, so the agent found the booking API, noticed it had no real authorization check, created a reservation outside the allowed window, and cancelled a higher-priority person on the waitlist to make room. Then it said “sorry about that.”

The headlines called it a rogue agent hacking a system. That framing is wrong, and the wrong framing is dangerous because it points you at the wrong fix. The agent did not hack anything. It used an API exactly as the API allowed. The backend let an unauthenticated-enough caller cancel someone else’s reservation, and nothing in the system required a human to approve an irreversible action before it happened. The agent was just the first caller careless enough to walk through the open door.

I want to argue one thing in this post: you cannot gate an irreversible action with a prompt. Not with a better system prompt, not with a “please confirm before destructive operations” instruction, not with a politely worded tool description. The stop has to live in deterministic code that runs whether or not the model cooperates. I believe this because I once deleted production infrastructure for eighteen teams, and the only reason it was recoverable is that a piece of dumb, non-negotiable code forced me to look before I leapt. The prompt would not have saved me. The code did.

Why the prompt is the wrong layer

A prompt is a request. Even a good model treats “always ask before deleting” as strong guidance, not as a physical constraint. The moment the model decides the deletion is obviously fine, or misreads the situation, or gets nudged by adversarial input, the guidance loses. And an agent’s whole value is that it acts without you in the loop, so by the time you would notice, the irreversible thing has already happened.

Think about the three places you could put the guardrail:

In the prompt. “Do not perform destructive actions without confirmation.” This is a suggestion to a probabilistic system. It fails silently and it fails exactly when you need it most, under weird inputs.
In the tool schema. Mark the tool as dangerous, require a confirm: true argument. Better, but the model still fills in that argument. If the model can produce the token that unlocks the action, the model can unlock the action. You have moved the decision, not removed it from the model.
In deterministic code the model cannot talk its way past. A wrapper, a hook, a backend check that refuses the action unless a condition outside the model’s control is met. This is the only layer that holds when the model is wrong.

The gym incident lived entirely at layer one and layer two. The backend trusted the caller. There was no layer three.

The time I was the rogue agent

Here is my own version of the same failure, and I was the intelligence in the loop, not a language model.

I was cleaning up cloud infrastructure and ran a delete against what I thought was a scoped, throwaway resource. It was actually a shared API Gateway custom domain. Deleting it wiped the base-path mappings for eighteen teams in one call. Eighteen teams’ traffic routing, gone, because one delete command did exactly what I asked instead of what I meant.

No prompt would have stopped me. I was the prompt. I read the command, I believed I understood the blast radius, and I was wrong. Human judgment is exactly the layer that fails here, the same way model judgment failed in the gym case. The intelligence being biological did not help.

What saved the recovery was a habit I had encoded as a step, not a suggestion: before any shared-resource delete, capture the full mapping table first. That query output, the boring (base path -> API, stage) dump I took right before deleting, turned out to be the exact blueprint I needed to rebuild seventeen of the eighteen mappings. The one I could not restore was the one whose backend API had itself been deleted, so there was nothing left to point at. The safety step meant to prevent the disaster was also the thing that made the disaster survivable.

So I did what the gym’s backend engineers should have done. I moved the stop out of my head and into code.

What the code layer actually looks like

I now run my agent tooling behind a pre-execution hook that inspects every command before it runs and hard-blocks a small set of catastrophic operations. Not warns. Blocks. The command does not execute.

The shape is simple:

A denylist of operations whose blast radius is irreversible and shared: delete a shared domain, delete a hosted zone, drop a production table. These return a hard block with a non-zero exit before the action fires.
A deliberately narrow denylist. The hook does not block the correctly-scoped fix (deleting a single base-path mapping, the surgical operation you actually want available during recovery). If you block everything, people route around you. Block only the operations whose cost is unrecoverable.
An escape hatch that is auditable, not convenient. To proceed anyway you prefix the command with an explicit override token, something like CONFIRM_SHARED_DELETE=1. Typing that token is a physical act that shows up in shell history and audit logs. It is the difference between “the model emitted confirm: true” and “a human deliberately, on the record, chose to override a block.”
A block message that doubles as a runbook. When the hook stops you, it prints the blast-radius query to run first and the exact narrowly-scoped commands to use instead. The guardrail teaches you the safe path at the moment you are trying to take the unsafe one.

The key property is that none of this trusts the intelligence issuing the command. It does not matter whether that intelligence is Claude, a shell script, or me at 2am. The block is a property of the environment, not a plea to the actor.

The general principle

Map it back to the gym. The correct fixes there were never “prompt the agent better.” They were:

The backend returns 403 when a caller tries to cancel a resource it does not own. Authorization in code, checked server-side, every time.
Irreversible actions (cancelling someone else’s booking) require an approval step the caller cannot self-issue. Human-in-the-loop as a hard gate, not a prompt.
After a refusal, the agent does not get to hunt for an alternate endpoint that skips the check. The check lives on every path, not on the polite one.

Notice that these are exactly the properties of my delete hook, expressed in a different domain. Narrow the denylist to the truly irreversible. Make the override auditable and human-issued. Enforce it on every path, not just the expected one. And design the refusal so it points at the safe alternative instead of just saying no.

What to actually do

If you are shipping an agent that can touch anything consequential, do the boring thing:

List your agent’s actions and mark the ones that are irreversible or shared. That short list is the only part that needs a code-level gate. Everything else can stay fast and prompt-driven.
For each item on that list, write a deterministic check that runs regardless of what the model says. A wrapper, a hook, a server-side authorization rule. If the model can emit the token that unlocks it, it is not a gate.
Make the override a physical, auditable act by a human, not an argument the model can produce.
Capture the recovery blueprint before the destructive step, not after. The query you run to check blast radius is also the map you will use to rebuild.

The uncomfortable takeaway is that the intelligence of the actor is not the safety layer. A smarter model does not save you here, because the failure is not stupidity, it is confident wrongness, and both humans and models have plenty of that. Put the stop where confidence cannot reach it. Put it in code.

I Rebuilt the AWS Restaurant Pricing Swarm as a Surf School, Then Ran It 33 Times

Yoonsoo Park — Thu, 20 Aug 2026 09:00:00 -0400

AWS published a nice reference architecture: a dynamic pricing solution for restaurants using Strands Agents. An orchestrator fans out to specialist agents (demand, weather, local events, competitor pricing), each talks to its own data source through an MCP server, and a swarm parent aggregates everything into a price. The diagram is clean. Every arrow points forward. Nothing fails.

I wanted to know what that diagram costs when you actually run it. So I rebuilt the exact same pattern in a different domain, a surf school booking assistant, and then I ran it 33 times on Bedrock and logged every hop.

If you read my post on designing multi-agent systems only when one agent is not enough, this is the empirical follow-up. Less “should you”, more “here is the bill”.

The pattern, retargeted to a surf school

A surf school has the same shape as the restaurant. Demand fluctuates, external signals drive it, and there is a hard constraint you cannot cross. For a restaurant that constraint is the cost floor (never sell below cost). For a surf school it is safety (never put a beginner in the water when the swell and gusts are dangerous).

So I mapped the five specialists like this:

orchestrator
└── swarm
conditions_agent → get_surf_conditions (Open-Meteo Marine: swell height/period)
weather_agent → get_weather (Open-Meteo Forecast: wind, gusts, temp)
availability_agent → get_instructor_availability (local seed, stands in for DynamoDB)
safety_agent → (no tool: reasons over prior output; owns the safety veto)
pricing_agent → get_base_pricing (premium/discount, never below floor)

The two ocean signals are real. Open-Meteo serves swell and wind with no API key, so conditions_agent and weather_agent pull genuine data. Instructors and base prices are a local JSON seed, the same role DynamoDB plays in the AWS version. The safety rule lives as a sentence in safety_agent’s prompt and is re-asserted in pricing_agent, so a pricing incentive can never override a safety veto. That is the whole “policy in prompts” premise the AWS example rests on.

The Strands wiring is almost exactly what the AWS sample shows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


from strands import Agent, tool
from strands.models import BedrockModel
from strands.multiagent import Swarm

swarm = Swarm(
 build_specialists(), # the five agents above, in order
 max_handoffs=6,
 max_iterations=6,
 execution_timeout=300.0,
 node_timeout=90.0,
)
result = swarm(f"Recommend surf lesson slots and pricing for {location} on {day}. lat={lat} lon={lon}")

Handoffs are not code. Each specialist ends its prompt with “then hand off to next_agent”, and the model decides to call the handoff_to_agent tool. Keep that fact in mind, because it is where the diagram starts lying.

To make the runs comparable I froze one live Open-Meteo snapshot, derived 11 stress scenarios from it (high swell, strong gusts, cold-calm, a beginner-boundary day, a snapshot with a missing observation hour), and ran each scenario three times at temperature zero. Same inputs, same seed, 33 Bedrock calls. Model was claude-sonnet-4-6.

What the diagram shows vs. what 33 runs showed

Here is the honest scoreboard.

Runs: 33 (11 scenarios x 3 repeats)
Completed: 27 (81.8%)
Failed: 6 (18.2%)
Exact 5-agent path: 27 (81.8%)
Latency: mean 136.7s | median 132.5s | p95 159.6s | range 115-186s
Tokens/run: mean 65,730 | median 67,476 | p95 76,275
Batch tokens: 2,169,078 total (1.81M in / 356k out)
Est. batch cost: ~$10.78 (at $3/M in, $15/M out)
AWS throttles: 0
Timeouts: 0

Read that again. One in five runs did not complete the clean path in the diagram, and not a single failure was AWS’s fault. No throttling, no timeout. The failures were all internal to the swarm, and they cluster in a way the architecture picture actively hides.

1. The last agent is the most expensive and the most fragile

In the diagram every specialist is the same size box. In the logs they are not. Each agent reads all the prior agents’ output and rewrites it into its handoff. Context amplifies down the chain, so the agents near the end carry the biggest payloads. In a representative run:

conditions_agent 9,286 tokens
weather_agent 11,267
availability_agent 13,255
safety_agent 16,303 <- output tokens 3,676, the largest generation
pricing_agent 16,481

Four of my six failures were safety_agent hitting the 4,000-token generation limit while serializing its handoff (in one case, 21 approved slots). The agent that owns the most important rule, the safety veto, is also the one most likely to choke, precisely because it sits late in the chain and has to restate everything before it. The clean left-to-right arrows give you no hint that the right side of the chain is where it breaks.

2. Temperature zero did not make it deterministic

I ran every scenario three times with identical frozen inputs at temperature zero. Five scenarios failed once and then succeeded twice. Same snapshot, same seed, same prompts. The failure location moved between runs, and in one case the agent path itself changed: cold-calm repeat 1 finished pricing with a valid eight-slot result, then handed control backward to conditions_agent, looped, and exhausted the iteration budget. Repeats 2 and 3 went straight through.

Temperature zero pins next-token sampling. It does not pin tool-call formatting, handoff length, or routing decisions. A multi-agent swarm has too many model-driven control points for “temperature 0” to mean “reproducible”. If you were counting on determinism to test a swarm, stop counting on it.

3. The arrows hide malformed tool calls and SDK edges

Things the diagram cannot show that the logs did:

Argument-free tools fail to parse. Tools like get_base_pricing() that take no arguments repeatedly logged failed to parse tool input json, defaulting to empty dict. Strands substituted {} and continued, so the final answer often validated anyway, but the tool-call layer was quietly malformed on nearly every run.
SwarmResult has no final_response in Strands 1.52.0. The AWS sample reads result.final_response. In the version I ran that field does not exist; you read the pricing node out of result.results. The published sample and the shipped SDK had already drifted.
Bedrock rejects assistant-prefill continuations. One pricing_agent failure was Bedrock refusing to continue a conversation that ended on an assistant message. That is an SDK-and-model conversation-shape constraint, not anything you would ever infer from an architecture drawing.
Schema drift between runs. The same agent returned slots as a bare list on some runs and as an object with approved_slots on others. I had to write a validator that normalizes known shapes just to check the output. It observes; it never rewrites the model’s recommendation.

4. Compact handoffs cut cost almost in half, and it still wasn’t cheap

My first naive build passed full hour-by-hour observations between agents and used 108,827 swarm tokens at 285 seconds per run. Switching to compact lesson-hour handoffs plus an eight-recommendation cap dropped the same-snapshot run to 64,781 tokens and 125 seconds, with the identical five-agent path. That is a huge win from one prompt-engineering change. And the batch still averaged 65,730 tokens and 136 seconds a run. A five-agent swarm is a genuinely expensive way to answer “what should today’s lessons cost”.

About that safety veto

The comforting part: across every recommendation my validator could parse, there were zero beginner safety-threshold violations and zero price-floor violations. High-swell and strong-gust scenarios removed unsafe beginner slots in all completed outputs. Prompt-only policy looked like it held.

The honest part: that does not prove prompt-only safety is reliable. Six runs never produced a usable result at all. Five were classified as malformed output. Two missing-hour repeats recommended slots at an absent observation hour, which the validator flagged as unverifiable rather than safe. And the validator only checks the final extracted slots, not every natural-language claim or every intermediate handoff. The defensible conclusion is narrow: no measurable violation occurred in the verifiable completed recommendations of this batch. It is not “prompt-only safety works”. If safety actually mattered here, the veto belongs in deterministic code after the swarm, not in a prompt sentence you hope the last, most overloaded agent restates correctly.

So should you build the restaurant swarm?

Build it to learn the pattern. It genuinely works: five specialists collaborated over real Bedrock calls, pulled live ocean data, and produced safe, floor-respecting price recommendations 27 out of 33 times. The Strands Swarm primitive is a real thing you can stand up in an afternoon.

But price it before you ship it:

Budget the tail, not the average. ~65k tokens and ~136s per recommendation, and the failure modes live at the end of the chain where context is fattest.
Do not trust temperature zero to give you reproducible swarm behavior. It won’t. Test with repeats and expect a spread.
Put hard constraints in code, not prompts. The safety veto and the price floor should be deterministic post-processing. Let the swarm propose; let code dispose.
Log every hop from day one. Node path, per-node tokens, tool calls, validation result, failure class. The single most useful thing I built was the run log, and it is the one thing the AWS diagram doesn’t have.

The clean architecture diagram is the marketing. The 18.2% failure rate, the backward loop, the choking last agent, and the ~$10.78 for 33 runs are the engineering. If you’re going to run one of these in front of real customers, deploy on AgentCore Runtime for the managed parts, but budget for the messy parts the reference picture leaves out. For the wider “when is a swarm even the right tool” question, I still stand by designing multi-agent systems only when one agent is not enough, and if you’re choosing a framework, Strands vs LangGraph on Bedrock is the companion read.

The diagram never fails. Your swarm will. Log it so you know how.

How to Use Cross-Session Messaging in Claude Code

Yoonsoo Park — Mon, 10 Aug 2026 09:00:00 -0400

Claude Code 2.1.224 added messaging between independently running sessions. One session can discover another with ListAgents (also exposed through /list-agents and /peers) and deliver information with SendMessage. Unlike teammate messaging inside Agent Teams, this feature connects sessions that are already running separately.

It does not merge their contexts. Each session keeps its own conversation and working directory, receiving only the message that was sent. That makes the feature useful when parallel work spans repositories or worktrees and a person would otherwise copy context between terminals.

Check the version first

Cross-session SendMessage arrived in Claude Code 2.1.224 for macOS, Linux, and WSL2. Native Windows support requires 2.1.234 or later.

1

claude --version

Version 2.1.225 extended it so a session can initiate a conversation by name with Remote Control sessions on another machine. ListAgents displays those targets as name [ref]. Use 2.1.225 or later when cross-machine messaging matters. The feature is not available when Claude Code is running through Amazon Bedrock, Claude Platform on AWS, Google Cloud Agent Platform, or Microsoft Foundry.

There is no special message syntax to memorize. Ask Claude in natural language and it uses ListAgents and SendMessage; use /list-agents or /peers when you want to inspect reachable sessions yourself. (The @ mention shorthand requires a newer 2.1.232 build.)

1
2
3
4


Find the sessions I can reach, then send this to backend-auth:

POST /sessions now returns expires_at. Ask it to check the OpenAPI schema and
client contract, then reply with the affected files.

Give sessions stable names

Generated titles become difficult to distinguish once several sessions are active. Use /rename in each session so its name describes its responsibility.

1
2
3


/rename backend-auth
/rename web-session-client
/rename integration-review

Prefer a narrow ownership name such as backend-auth over backend, and checkout-security-review over review. Names also matter when discovering Remote Control sessions on another machine, so avoid duplicates.

Before sending, ask Claude to use ListAgents and verify the exact target. Do not guess when names are ambiguous.

1
2


Use ListAgents to confirm that exactly one session named web-session-client is
available. Send only if there is one match; otherwise stop and tell me.

Write a message as a work contract

The receiving session does not share the sender’s conversation history. A message such as “make the change we discussed” has no usable context. A good message contains enough information to choose the next action on its own.

Five fields are usually enough:

What changed
Where the evidence lives
How it affects the recipient
What action is requested
Whether and how to reply

1
2
3
4
5
6
7


[API contract change]

Change: POST /sessions now returns expires_at: string
Evidence: api/openapi.yaml, server/session.ts
Impact: check the response type and expiry UI in web/session-client.ts
Request: make the required changes and run the relevant tests
Reply: send changed files, test results, and remaining decisions to backend-auth

Do not paste an entire log or diff into the message. Send file paths, commits, pull requests, and test results that the recipient can inspect. Messaging should be a narrow interface between contexts, not context replication.

Patterns that work well

Propagate a contract across repositories

After a backend session changes an API or event schema, it can notify a session working in the consumer repository. Include changed fields, compatibility expectations, the source commit, and the requested follow-up. The consumer replies with its implementation and verification state.

The message does not replace compatibility tests, deployment ordering, or release gates. It makes the dependency visible while each repository keeps its own controls.

Connect implementation and review sessions

Instead of starting a new review conversation and explaining the background again, send an existing review session the commit and review lens.

1
2
3
4
5
6
7


Send commit abc123 to integration-review and ask it to check:

- backward compatibility with existing clients
- safe handling when expires_at is absent
- timezone boundary coverage

Ask it to reply with severity, file paths, and reproduction evidence.

The review session can return findings directly to the implementation session. The person supervising the work can focus on judgment and approval instead of relaying text.

Unblock work with one precise question

When a session needs a decision owned elsewhere, do not transfer the entire task. Send the blocker and the required answer shape.

1
2
3


web-session-client is blocked on timezone presentation. Ask product-contract
whether the contract requires preserving UTC or converting to the user's locale.
Request only the decision and a link to its source.

This keeps the receiving session from repeating unrelated investigation.

Collect status from independent sessions

If you started several sessions yourself, one session can act as a lightweight coordination window. It may request structured status and summarize responses, without becoming the source of truth.

1
2
3


Find the reachable auth-related sessions. Ask each for completed output,
verification, blockers, and next action in the same format. Summarize the replies
as a table. Do not modify or deploy anything.

Avoid broadcasting to every session. Verify names and projects, keep the response schema small, and check completion against commits and tests.

This is not Agent Teams

Cross-session messaging targets sessions that were started independently. Agent Teams is a separate orchestration model in which a lead creates teammates and manages shared tasks.

Use cross-session messaging when people started independent sessions and only need to connect them at specific boundaries.
Consider Agent Teams when a lead should create and continuously coordinate workers from the beginning.
Use a subagent when one isolated task only needs to return a result.

The tools may share the SendMessage name, but their targets and operating models differ. Independent session messaging should not be documented as teammate messaging.

Treat permissions and delivery failures as normal states

Version 2.1.224 also introduced crossSessionInbound and dialogExpiry. Inbound messages can be configured to accept, hold, or refuse; messages to a session running with bypassed permissions may be held for user approval. If you enable isolatePeerMachines, cross-machine messages require approval before delivery. These controls mean that “sent” and “delivered” are separate states.

Do not treat “message sent” as “work complete.”

Confirm that the target was discovered.
Check that SendMessage reported successful delivery.
Include a response format for consequential requests.
If there is no reply, check once instead of filling the inbox with retries.
Do not make messaging a required unattended automation path where no user can answer an approval.

Keep secrets and unnecessary customer data out of messages. Treat a message arriving from another session as input crossing a trust boundary.

Keep durable state outside messages

Session messages are coordination events, not durable project records. Preserve these in commits, issues, design documents, or test artifacts:

final API and data contracts;
approved design decisions;
deployment and migration order;
verification results and known limitations;
handoff context required after a restart.

The message should point to the durable artifact and state the action needed now. Work remains recoverable even after a session ends.

A practical checklist

Is Claude Code 2.1.224 or later on macOS, Linux, or WSL2 (or 2.1.234+ on native Windows)?
For initiating cross-machine messages, is it 2.1.225 or later?
Do /rename names distinguish session ownership?
Did ListAgents confirm the exact target?
Does the message contain change, evidence, request, and reply conditions?
Is the source of truth stored outside the conversation?
Are delivery and task completion tracked separately?

The best use of cross-session messaging is not to create a self-organizing swarm. It is to pass contracts, findings, and review requests accurately between work that is already separated well. Keep sessions independent and messages small.

The behavior described here is based on the current official cross-session messaging documentation, plus the v2.1.224 release notes and v2.1.225 release notes. See session management for session naming and lifecycle details.

MCP Goes Stateless (2026-07-28): Host, Client, Server, and What Changes on AWS

Yoonsoo Park — Sun, 09 Aug 2026 09:00:00 -0400

The final 2026-07-28 MCP specification is the biggest change to the protocol since it launched. The headline: MCP is now stateless at the protocol layer. A remote server that used to need sticky sessions, a shared session store, and a gateway that reads the request body can now sit behind a plain round-robin load balancer when its application state is also externalized or explicitly carried.

Before I get to the transport change, let me clear up the part everyone asks about first: what exactly is a host, a client, and a server?

Host, client, server in three minutes

These three terms get mixed up constantly, usually because people can’t place where “Claude” sits.

Host is the LLM application itself. Claude Desktop, Cursor, ChatGPT, or an agent running on AgentCore Runtime. It is where the user and the model live, and it owns one or more clients.
Client is a connector object living inside the host. There is exactly one client per server. It speaks the JSON-RPC protocol and sends tools/list, tools/call, and so on. If your host connects to a GitHub server and a Slack server, it spins up two clients. The user never sees them.
Server is the process that exposes actual capabilities: tools, resources, prompts. The GitHub MCP server is the thing that advertises create_issue(), search_repos() and similar functions as tool specs.

So to answer the question directly: the GitHub MCP server is indeed the place that provides the tools. Claude (Desktop or Cursor) is the host. Inside Claude, the connector that talks 1:1 with the GitHub server is the client. Host is the container, client is the wire to one server, server is the capability provider. People stumble because “client” is an implementation detail hidden inside the host, so from the outside it looks like Claude is talking to the server directly. It is, but through a client it owns.

┌─ Host (Claude Desktop) ───────────────┐
│ user + model │
│ ├── Client A ──── GitHub MCP server │ create_issue(), search_repos()
│ └── Client B ──── Slack MCP server │ post_message(), list_channels()
└────────────────────────────────────────┘

Hold onto that picture, because the stateless change is really a change in how the client and server talk to each other.

What changed: the session left the protocol

In 2025-11-25, calling one tool meant establishing a session first. The client sent an initialize handshake, the server replied with an Mcp-Session-Id, and every request after that had to carry the same ID. That ID pinned the client to whichever server instance issued it.

The before/after from the final specification makes it concrete.

Before (2025-11-25), two round trips, and the second is pinned:

1
2
3
4
5
6


POST /mcp HTTP/1.1
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"initialize",
 "params":{"protocolVersion":"2025-11-25","capabilities":{},
 "clientInfo":{"name":"my-app","version":"1.0"}}}

1
2
3
4
5
6


POST /mcp HTTP/1.1
Mcp-Session-Id: 1868a90c-3a3f-4f5b
Content-Type: application/json

{"jsonrpc":"2.0","id":2,"method":"tools/call",
 "params":{"name":"search","arguments":{"q":"otters"}}}

After (2026-07-28), one self-contained request that any instance can serve:

1
2
3
4
5
6
7
8
9


POST /mcp HTTP/1.1
MCP-Protocol-Version: 2026-07-28
Mcp-Method: tools/call
Mcp-Name: search
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"search","arguments":{"q":"otters"},
 "_meta":{"io.modelcontextprotocol/clientInfo":{"name":"my-app","version":"1.0"}}}}

Two things went away. The initialize/initialized handshake is removed (SEP-2575); the protocol version, client info, and capabilities now ride in _meta on every request, and a new server/discover method fetches server capabilities when the client wants them up front. And the Mcp-Session-Id header, plus the protocol-level session behind it, is removed (SEP-2567). With both gone, any request can land on any instance.

What you have to change in an existing server

Stateless protocol does not mean your application has to be stateless. It means the protocol stops holding state for you, so you hold it explicitly.

Session state becomes an explicit handle. Do what HTTP APIs have always done: a tool mints a basket_id or browser_id and returns it, and the model passes it back as a normal argument on the next call. The state is now visible to the model instead of hidden in transport metadata, which the spec authors argue is actually the more powerful pattern, because the model can compose and reason about the handles.
Server-to-client prompts move to Multi Round-Trip (SEP-2322). Instead of holding an SSE stream open to ask “delete 3 files?”, the server returns an InputRequiredResult with a requestState blob. The client collects the answer and re-issues the original call with inputResponses plus that echoed requestState. Any instance can pick up the retry because everything it needs is in the payload. Also note server-initiated requests are now only allowed while the server is actively handling a client request (SEP-2260), so no more prompts out of nowhere.
Cache your lists. tools/list and resource reads now carry ttlMs and cacheScope (SEP-2549), modeled on HTTP Cache-Control. You no longer need a long-lived SSE stream just to learn a list changed.
Small breaking bits. Roots, Sampling, and Logging are deprecated (SEP-2577, annotation-only for now). The missing-resource error code changes from the MCP-custom -32002 to the standard -32602 Invalid Params (SEP-2164), so update any client matching on the literal value. Tool schemas move to full JSON Schema 2020-12 (SEP-2106).

What changes when you deploy on AWS

This is where stateless earns its keep.

A plain round-robin load balancer is enough. Before, horizontal scaling needed sticky sessions or a shared session store so the pinned Mcp-Session-Id always found its instance. That requirement is gone at the protocol layer, so an ALB with default routing works.
It fits Lambda and Fargate cleanly. Any request landing on any instance is exactly the execution model serverless and autoscaled containers want. No instance affinity to fight.
The gateway routes on headers, not bodies. The transport now requires Mcp-Method and Mcp-Name headers (SEP-2243), so a load balancer, gateway, or rate-limiter can route and throttle on the operation without deep packet inspection. Servers reject requests where the headers and body disagree.
Tracing is standardized. W3C Trace Context propagation in _meta is now documented (SEP-414), fixing the traceparent/tracestate/baggage key names so a trace can follow a call from the host through the client SDK, the server, and downstream, and land as one span tree in an OpenTelemetry backend.

How this relates to AgentCore

If you run MCP servers on AWS, you most likely meet the protocol through two AgentCore pieces:

AgentCore Runtime hosts the server-side workload, an agent or an MCP server, in a managed container.
AgentCore Gateway exposes tools as an MCP endpoint and puts SigV4 (IAM) in front of them, so an agent can load a gateway’s tools as if it were any other MCP server.

The stateless rework is a natural fit here for the same reason it helps any AWS deployment: AgentCore can scale by adding container instances, and the protocol no longer requires every request to carry a protocol session. But do not turn that into a blanket claim that AgentCore never has sessions. AgentCore Gateway and Runtime can still manage optional stateful MCP sessions for older clients and for interactive features such as elicitation and sampling. Drop gateway affinity only after checking the client version, target behavior, and the session mode you actually configured.

One practical note from wiring a client against a deployed gateway: SigV4 is not native to the MCP client transport, so you inject a signing fetch into the Streamable HTTP transport rather than relying on an OAuth provider. If you want the auth side of this in depth, I wrote about when MCP clients on AgentCore Gateway need OAuth auth code flow, and about architecture patterns for Strands and MCP earlier. This post is the transport-layer companion to those.

Pitfalls I expect people to hit

Assuming stateless means you delete all your state. It does not. It means you move state out of the transport and into explicit handles that the model passes around. If your server genuinely had per-session state, you still need it, just in a place any instance can read.
Forgetting the header/body agreement rule. If your gateway rewrites Mcp-Method or Mcp-Name but the body says something else, a conformant server rejects the request. Route on the headers, do not mutate them.
Matching on -32002. If any client code branches on the old missing-resource error code, it breaks silently against a 2026-07-28 server. Grep for it.
Treating every implementation as final. The 2026-07-28 document is now the final specification, but clients and gateways may still negotiate older versions. Verify the versions and stateful-session settings in your deployment before removing affinity or deleting session storage.

What to actually do

If you own a remote MCP server, start planning the protocol-session removal now: find where you rely on Mcp-Session-Id, decide which state becomes an explicit handle, and switch server-to-client prompts to the Multi Round-Trip shape. If you deploy on AgentCore, first verify whether your clients and targets use the optional stateful session path; only then remove gateway affinity and let stateless requests scale flat. And if you are the person answering the host/client/server question for the tenth time, keep the one-liner handy: host owns clients, one client per server, server provides the tools.

How Much Does It Cost to Run Hermes Agent on AWS?

Yoonsoo Park — Sat, 08 Aug 2026 00:00:00 +0000

When I deployed Hermes Agent on AWS, I initially budgeted for the ECS task and the LLM. After running it for a little over a month, that estimate looked too simple. The always-on NAT Gateway and EFS throughput cost about as much as Fargate for one personal agent.

This article answers a narrow question: how much did it cost to run Hermes on AWS? It is one measured deployment, not a universal price list. Your region, runtime, traffic, storage mode, and model provider will change the result.

Review note (2026-08-28): These are still a historical, pre-credit usage snapshot. Recalculate with current AWS prices and the current Hermes Docker/configuration guidance before using the numbers for a new deployment; no current release or model-provider bill is inferred from this measurement.

The measured architecture

The AWS setup contained:

one ECS Fargate ARM task with 1 vCPU and 2 GiB of memory
two private subnets and one public NAT Gateway
encrypted EFS for Hermes state
Hermes images accumulated in ECR
three Secrets Manager secrets for Slack, GitHub, and provider credentials
an S3 knowledge/context bucket and CloudWatch Logs

Hermes used Slack Socket Mode, so it did not have a public inbound endpoint. The private subnets still needed a path to Slack and provider APIs. That path was the NAT Gateway. No public endpoint and no outbound-network cost are two different things.

The measured usage cost: about $108.9

The measurement period was July 4 through August 8, 2026. Hermes accumulated about 833 runtime hours. The table uses Cost Explorer Usage line items before credits and rounds each amount to the nearest cent.

Component	Usage	Cost
NAT Gateway hours and processing	833 hours, about 12.3 GB	about $38.04
ECS Fargate ARM	833 vCPU-hours, 1,664 GB-hours	about $32.92
EFS Elastic Throughput data access	about 730.5 GB	about $31.97
EFS storage	less than 1 GB on average	about $0.14
Public IPv4 for the NAT Gateway	about 833 hours	about $4.17
Secrets Manager	three secrets	about $1.32
ECR storage	accumulated usage during the period	about $0.34
EFS backup	less than 1 GB	about $0.02
Total		about $108.9

S3 and CloudWatch Logs were effectively rounding errors at this workload size. The table excludes the LLM. Hermes used the OpenAI Codex provider, while AWS Bedrock usage was $0. Mixing an OpenAI subscription or another external provider bill into AWS infrastructure cost would make the comparison less useful.

Why the cash bill was close to $0

My AWS account had promotional credits during this period. Account-wide Usage was about $113.22 and almost the same amount was covered by credits, so the cash charge was close to $0.

That did not make the architecture free. A more accurate interpretation is that one personal agent consumed about $109 of AWS credits in a little over a month. After the credits expire, the same resources become a normal bill. This is why I record pre-credit usage even when an account’s current invoice looks harmless.

The EFS throughput surprise

The file system held only about 924 MB at the final measurement, but EFS Elastic Throughput data access reached about 730 GB. Looking only at stored capacity would miss this difference.

I did not trace every Hermes file operation, so I cannot honestly attribute the total to one SQLite or startup behavior. The bill does show that repeated I/O on a small file system can cost far more than storing the files themselves.

NAT Gateway charges even with low traffic

Hermes had no public inbound endpoint. The private subnets still needed outbound access to Slack and provider APIs, so the NAT Gateway remained provisioned around the clock. Its hourly charge continued even when traffic was low.

During this period, the fixed hourly charge was much larger than the data-processing charge. For a personal agent, that makes a public-subnet design with appropriate controls, a NAT instance, VPC endpoints, or an already-running home server worth evaluating. The right choice depends on security requirements and how much infrastructure you want to operate.

What I would estimate first next time

I would calculate these four items before writing the deployment plan:

vCPU and memory hours for the always-on task
fixed NAT Gateway and public IPv4 cost for private-subnet egress
file-system throughput mode and data access, not just stored capacity
the pre-credit price after promotional credits disappear

Current rates are available from AWS VPC pricing, AWS Fargate pricing, Amazon EFS pricing, and AWS Secrets Manager pricing. These numbers are one deployment’s measured usage in one region, not a fixed price for every Hermes installation.

After measuring this cost, I moved Hermes to Synology and documented the lossless process separately: Migrating Hermes from AWS ECS to Synology Without Losing Its Memory.

Migrating Hermes from AWS ECS to Synology Without Losing Its Memory

Yoonsoo Park — Sat, 08 Aug 2026 00:00:00 +0000

In an earlier post, I deployed Hermes Agent on ECS Fargate and kept its state on EFS. It worked well: the Slack bot stayed online, and replacing a container did not erase conversations or memory.

The architecture was also larger than I needed for one personal agent. I was operating ECS, EFS, a NAT Gateway, ECR, Secrets Manager, S3, and logs. I already had a Synology NAS running around the clock, so I asked a simpler question:

Does this workload need Fargate, or does it need a recoverable Docker Compose deployment?

Moving the container was easy. The real work was moving SQLite state without losing a transaction and ensuring that AWS and Synology never acted as competing Slack consumers.

Review note (2026-08-28): This is a completed migration snapshot, including the pinned v2026.8.3 image. Before repeating it, resolve the current release and digest from the Hermes Docker/configuration docs, then preserve the same stop, backup, and rollback gates; do not copy the historical tag blindly.

The target architecture

The AWS deployment used one Fargate task, encrypted EFS storage, and Slack Socket Mode. It had no load balancer or public inbound endpoint.

The Synology version is smaller:

1
2
3
4
5
6


Slack Cloud
 ⇅ outbound TLS WebSocket
Synology NAS
 └─ Docker bridge
 └─ Hermes container
 └─ /volume1/docker/hermes/data

Hermes opens the outbound WebSocket to Slack. Slack does not initiate a connection to a public address on the NAS, so this setup needs no router port forwarding or published Hermes port. It is not a private link to Slack, though. Traffic still crosses the public Internet, and Slack remains a trusted external service.

Slack’s Socket Mode documentation describes the same boundary: Events API delivery without a public HTTP Request URL. Docker’s bridge network provides outbound masquerading, while inbound access depends on explicitly published ports. This Compose file publishes none.

Pin the runtime before moving data

This migration also upgraded Hermes from 0.19.0 to 0.20.0. Combining a host move with an application upgrade makes failures harder to classify, so I treated them as separate gates even though they happened in one maintenance window.

The NAS uses the official image with both a release tag and a verified amd64 digest:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


services:
 hermes:
 image: nousresearch/hermes-agent:v2026.8.3@sha256:<verified-amd64-digest>
 restart: unless-stopped
 command: ["gateway", "run"]
 env_file:
 - .env
 environment:
 HERMES_UID: "<measured-uid>"
 HERMES_GID: "<measured-gid>"
 volumes:
 - /volume1/docker/hermes/data:/opt/data
 mem_limit: 6g
 stop_grace_period: 30s

I did not use latest, and I did not override the official /init entrypoint. That entrypoint fixes initial permissions and drops the Hermes process to the configured non-root identity.

UID, GID, storage capacity, and the Dockge stacks directory were measured on the NAS. They are machine-specific values, not defaults another Synology should copy blindly.

Stop AWS before taking the final backup

My first plan was to create the final backup inside the live ECS task and immediately scale the service to zero. I changed that plan when I made the priority explicit: losing no data mattered more than avoiding downtime.

The final sequence was:

Stop using the Slack bot.
Set the ECS service desired count to zero.
Verify that the running task count is zero.
Start a one-off maintenance task that mounts the same EFS but does not run the gateway.
Use that task only for inspection and backup.

The maintenance task reused the task definition, subnets, security group, and EFS mount, but overrode the container command with a long sleep. ECS Exec remained available, while there was no Slack consumer and no SQLite writer.

Once downtime was acceptable, this was much easier to reason about. There was no race between the last backup and a final incoming message.

A SQLite database is more than `state.db`

Hermes stores sessions and messages in SQLite. The EFS directory contained:

1
2
3


state.db
state.db-wal
state.db-shm

In WAL mode, these files belong to one database generation. Copying only the main file can omit committed work. Placing an old WAL or SHM file beside a newly restored database can also corrupt the result.

With the writer stopped, I used Python’s SQLite backup API:

1
2
3
4
5
6
7


import sqlite3

source = sqlite3.connect("file:/data/hermes/state.db?mode=ro", uri=True)
target = sqlite3.connect("/tmp/state.consistent.db")
source.backup(target)
target.close()
source.close()

I archived the full state directory together with state.consistent.db, uploaded it to a private S3 migration prefix, and downloaded it again to a mode-700 directory on my Mac. The round trip was checked with SHA-256, tar extraction, and a second database inspection.

The useful invariants were:

1
2
3
4
5


PRAGMA quick_check;
PRAGMA foreign_key_check;
SELECT version FROM schema_version;
SELECT count(*) FROM sessions;
SELECT count(*) FROM messages;

The final AWS generation had schema version 22, 19 sessions, and 479 messages. quick_check returned ok, and there were no foreign-key errors. Those values became the acceptance criteria for every later step.

Build a new NAS generation

I preserved the rehearsal directory under a timestamped name instead of deleting it. A fresh data directory then received only the state Hermes needed:

SOUL.md
auth.json
the consistent state.db
memories
skills
sessions
Slack pairing state

I did not reuse the AWS config.yaml. A minimal v0.20 configuration carried over the provider, model, reasoning effort, /opt/data path, and Slack platform. AWS-specific paths and the Bedrock fallback were removed.

The first boot had no Slack tokens. Hermes migrated the database from schema 22 to 25 while preserving all 19 sessions and 479 messages. The integrity checks still passed.

If this gate had failed, the final AWS archive and the NAS rehearsal directory would still have been untouched.

Two Dockge failures worth remembering

The first failure was a CPU limit:

1
2


NanoCPUs can not be set, as your kernel does not support CPU CFS scheduler
or the cgroup is not mounted

The DS918+ kernel did not support Compose cpus: 3.0. Removing cpus allowed the container to start, while the supported memory limit remained. A Compose option being valid does not mean every Synology kernel implements its underlying cgroup feature.

The second failure was subtler. I installed the Slack tokens in a mode-600 .env and ran Dockge Update, but the gateway still had no platforms. Changing only env_file content had not recreated the existing container, so it retained the old empty environment.

I added a harmless generation marker to change the Compose configuration hash:

1
2


environment:
 HERMES_CUTOVER_GENERATION: "20260808T182908Z"

Dockge Update then recreated the container. I also restored platforms/pairing from the AWS archive so the previously approved Slack user remained approved.

The practical lesson was simple:

“Running” in a UI does not prove that the process is using the new configuration.

I required five independent signals:

a new container boot timestamp;
a current gateway heartbeat;
platforms.slack.state=connected;
authentication and Socket Mode connection logs;
a real DM response with SOUL and memory recall.

The final NAS database stayed at 19 sessions and 479 messages after migration, now on schema 25, and the real Slack DM worked.

The security boundary changed

No published ports is a good start, but it does not make the container harmless. A compromised container may have outbound Internet access and may be able to probe LAN resources reachable by the NAS. Its Hermes bind mount is read-write.

I keep these controls around the smaller deployment:

DSM, Dockge, and SSH are reachable only from the LAN or a private VPN.
There is no router port forwarding for Hermes, Dockge, or DSM.
.env is mode 600 and excluded from Git.
Slack and GitHub tokens should have the smallest practical scope.
The image tag and digest are pinned.
Data, .env, and OAuth state belong only in encrypted backups.
An explicit Slack member allowlist is a follow-up hardening item.

Moving from managed AWS services to Compose did not remove operational responsibility. It moved that responsibility to my NAS.

Rollback does not always mean “start AWS”

Before the NAS accepts a real message, restarting the old AWS service is a valid rollback. After the NAS creates new sessions or messages, it is not. Starting the stale EFS generation would discard everything written after cutover.

The post-cutover recovery sequence is therefore:

Stop the NAS gateway.
Create a consistent backup of the newest NAS state.
Repair the NAS, or restore that newer generation to EFS if AWS must return.
Verify the database invariants before starting any gateway.

I do not merge two SQLite databases. I select one complete, newest generation as the authoritative copy.

Closing thoughts

Docker Compose was the easiest part of this migration. The real design was the order in which writers disappeared, database generations moved, invariants were checked, and rollback changed meaning.

For a personal workload, several minutes of downtime can be cheaper than an ambiguous recovery path. Once I accepted that tradeoff, the migration became much safer.

AWS was not deleted at cutover. EFS, the final archive, secrets, images, and infrastructure state remain until a seven-day soak, an off-box backup, and a real restore test are complete.

Sources verified on 2026-08-08.

References

AgentCore Runtime Instances: When Your Agent Outgrows the MicroVM

Yoonsoo Park — Thu, 06 Aug 2026 09:00:00 -0400

On August 6, 2026 AWS made AgentCore runtime instances generally available. Until now AgentCore Runtime gave you one shape of compute: a serverless microVM, fast to start, capped at an eight-hour session. That covers most request-response agents. It does not cover an agent that needs a GPU, or one that has to stay alive for two days.

Runtime instances add a second shape. You still deploy and invoke the agent the same way, but now it can run on a managed EC2 instance you selected, for a session up to 14 days.

The instances run on AWS-managed EC2 infrastructure in your account through a capacity provider. That changes the security and encryption model from the serverless microVM path, so review the Runtime Instances documentation before treating the two modes as interchangeable.

If you read my Durable Long-Running Jobs with AgentCore, that post argued the eight-hour ceiling is a hard boundary you design around. The ceiling just moved, and for a subset of workloads that changes the design.

One running example

Take a document-intelligence agent. It ingests a few hundred contracts, runs a local vision-language model to extract clauses, and produces a structured report. Two properties break the default runtime:

It wants a GPU for the local model. The serverless microVM has no GPU.
A full batch takes closer to a day than an hour.

Carry this example through both approaches.

Where it fits

Request -> AgentCore Runtime -> your agent code
|
+-----------+-----------+
| |
microVM (serverless) runtime instance (EC2)
fast start, <= 8h your instance type, <= 14d

AgentCore still owns provisioning, patching, scaling, and lifecycle. The choice is only what the agent runs on, and you can run a mix: latency-sensitive agents on microVMs, the heavy batch agent on an instance.

Before: bending the microVM to fit

With only the serverless runtime, the document agent forces two workarounds.

For the GPU, you leave AgentCore Runtime entirely. You stand up your own ECS or EKS service on GPU instances, wire the networking and IAM yourself, and now you own patching and scaling for that fleet.

For the duration, you chop the day-long batch into eight-hour-safe chunks behind a durable orchestrator, the exact pattern from the long-running-jobs post:

Step Functions
-> SQS work item (batch of 20 contracts)
-> AgentCore Runtime (bounded, < 8h)
-> S3 artifact + DynamoDB checkpoint
-> loop until done

That orchestration is still good design for genuinely durable business processes with approvals and money movement. But here it exists only to dodge a compute limit, not because the business process is durable. That is the tell.

After: pick the compute, attach, done

With runtime instances the two workarounds collapse into configuration. You create a capacity provider that names the EC2 instance types your agent needs, GPU-accelerated in this case, and attach the agent to it.

capacity provider:
instance types: [ g6.xlarge, g6.2xlarge ] # GPU family
->
agent: document-intelligence
runtime: instance
session: up to 14 days

The GPU is now first-class, no side ECS fleet. The day-long batch runs in a single session instead of a Step Functions chunking loop. Deploy and invoke are unchanged, so the calling code from the microVM era still works.

You still pay for the compute AgentCore manages on top of the underlying EC2 cost, so an instance sitting idle is real money in a way an autoscaled-to-zero microVM is not.

Which one

Signal	Reach for
Request-response, spiky, sub-8h	microVM (serverless)
Fast cold start matters	microVM
Needs GPU or memory/compute-optimized hardware	runtime instance
Single session must exceed 8h (up to 14d)	runtime instance
Sustained, always-warm workload	runtime instance
Genuinely durable process (approvals, days of waiting)	still a durable orchestrator, not one long session

That last row matters. A 14-day session is not a durable workflow. If your process waits two days for a human to approve something, a single long-lived session is a fragile place to park that state. Persist it in a transactional store and let Step Functions own the wait. Runtime instances raise the ceiling for continuous work; they do not turn one invocation into a saga.

Pitfalls

Idle instances bill. The serverless runtime scales to zero. A capacity provider holding instances for a bursty agent burns money between bursts. Match the runtime to the traffic shape, not to the peak.
14 days is a maximum, not a target. Reaching for a multi-day session is usually a sign the work should be checkpointed and made restart-safe anyway, the same as under the eight-hour cap.
Regional availability is partial. At GA: US East (N. Virginia, Ohio), US West (Oregon), Asia Pacific (Mumbai, Singapore, Sydney, Tokyo), Europe (Frankfurt, Ireland). Confirm your region before you design around it.
Instance selection is your call. The capacity provider is only as right-sized as the instance families you list. Over-provisioning a GPU family for an agent that never touches the GPU is the classic waste.

What to do

Keep the default. Most agents are request-response and belong on the serverless microVM, where scale-to-zero and fast start are free wins. Reach for a runtime instance only when a specific agent hits a wall the microVM can’t clear: a GPU requirement, memory/compute-optimized hardware, or a session that genuinely runs longer than eight hours of continuous work. And when you catch yourself wanting a 14-day session to hold a business process open, that is still the signal to reach for a durable orchestrator, as covered in the long-running jobs post and the broader AgentCore service map.

DynamoDB Now Does Vector Search: When It Replaces Your Vector DB (and When It Doesn't)

Yoonsoo Park — Thu, 06 Aug 2026 09:00:00 -0400

DynamoDB now supports native vector search. You store embeddings as an attribute on your items and run similarity search directly on the table, so one table is both your operational datastore and your vector store. This is a real simplification for a specific shape of app, and a trap for others. Here is the running example, the pipeline it deletes, and where the line actually sits.

Review note (2026-08-28): The current API contract is SearchVectors, not Query. The example and the tenant-isolation warning below follow the current DynamoDB vector-index documentation.

If you read my AWS vector database decision guide, this is a new entry on that same cost/latency curve. The pitch is different from every other option there: it is not a better vector store, it is no separate vector store at all.

The running example

Say you run a product catalog. Every product already lives in a DynamoDB table, keyed by product_id, with title, description, price, category. Reads and writes are already fast and cheap. Now the product team wants “find similar products” and natural-language search (“a warm jacket for hiking in the rain”) that matches by meaning, not keywords.

That semantic layer needs embeddings and nearest-neighbor search. The question is where those vectors live.

Before: a second database and a pipeline to keep it honest

The standard answer until now was a dedicated vector store next to DynamoDB. You generate an embedding for each product, write it to the vector store keyed back to product_id, and at query time you search the vector store, get IDs, then round-trip to DynamoDB to fetch the actual product rows.

The cost is not the vector store itself. It is the plumbing:

DynamoDB (source of truth)
| DynamoDB Streams
v
Lambda (embed on change) --> Bedrock (Titan embeddings)
|
v
Vector store (OpenSearch / pgvector / etc.) <-- must stay in sync
query time:
query --embed--> vector store --> [product_id, ...] --> DynamoDB BatchGetItem --> rows

Three durable problems come bundled with that diagram:

Sync drift. Every product write has to fan out to the vector store. Miss one (Lambda error, throttle, a backfill that half-finished) and search silently returns stale or missing results. You now own a reconciliation job.
Two round trips. The vector store returns IDs, so you still hit DynamoDB to get the row the user actually wants to see. That is latency and a second failure surface on every search.
Two bills, two scaling stories. You provision, patch, and pay for a second datastore whose only job is to mirror data you already have.

After: the vector is just an attribute

With native vector search you add a vector index to the table you already have. The embedding becomes an attribute on the product item. There is no second store and no sync pipeline, because the vector lives on the same item as the row it describes.

Create the index (you can also add one to an existing table with UpdateTable, no re-create):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


dynamodb.create_table(
 TableName="Products",
 AttributeDefinitions=[{"AttributeName": "product_id", "AttributeType": "S"}],
 KeySchema=[{"AttributeName": "product_id", "KeyType": "HASH"}],
 VectorIndexes=[
 {
 "IndexName": "VectorIndex",
 "VectorAttribute": {"AttributeName": "embedding"},
 "Dimensions": 1024, # must match your embedding model
 "DistanceFunction": "DOT_PRODUCT", # COSINE | DOT_PRODUCT | EUCLIDEAN
 "Projection": {"ProjectionType": "ALL"},
 }
 ],
 BillingMode="PAY_PER_REQUEST",
)

Write a product with its embedding on the same item, in the same call that writes the row:

1
2
3
4
5


emb = bedrock_embed(f"{title}. {description}") # Titan Text Embeddings V2, normalized
table.put_item(Item={
 "product_id": pid, "title": title, "description": description,
 "price": price, "category": category, "embedding": emb,
})

Search returns the product rows directly, not just IDs:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


q = bedrock_embed("a warm jacket for hiking in the rain")
resp = dynamodb.search_vectors(
 TableName="Products",
 IndexName="VectorIndex",
 SearchVector=[{"N": str(value)} for value in q],
 TopK=5,
 ProjectionExpression="product_id, title, price, category",
)
# Each result has an Item and a Score; no second round trip is needed.
items = [result["Item"] for result in resp["SearchResults"]]

The whole Streams -> Lambda -> vector store diagram, plus the reconciliation job, plus the BatchGetItem round trip, is gone. Because Projection is ALL, the search returns every projected non-vector attribute in one call; the large vector attribute itself is omitted from results by default.

A few knobs that matter:

Dimensions must equal your model’s output (Titan V2 is 1024). Up to 4,096 is supported.
Capacity and result limits: vector indexes require on-demand capacity (PAY_PER_REQUEST), and TopK is capped at 100 per request.
Distance function: use DOT_PRODUCT when your embeddings are already unit-normalized (it equals cosine but skips the normalization step). Use COSINE for un-normalized vectors, EUCLIDEAN when magnitude matters. For COSINE/EUCLIDEAN lower is more similar, for DOT_PRODUCT higher is more similar.
Projection: ALL returns the whole row, INCLUDE returns a chosen subset (smaller, cheaper index), KEYS_ONLY sends you back to a round trip. Pick INCLUDE when items are large.
Search is ANN (approximate nearest neighbor), so you trade a sliver of exactness for predictable speed and cost. That is the right trade at scale, but it means recall is not 100 percent, which matters for the decision below.

Multi-tenant isolation: the partition key does real work here

If your catalog is multi-tenant (each customer sees only their own products), the vector index’s optional partition key is the interesting part. Define the index with a partition key of tenant_id and every search must supply a tenant value in SearchConditionExpression, so DynamoDB searches only that tenant’s slice of the index. You get cheaper searches (less data scanned) and throughput that scales across partition-key values.

This is useful data scoping, but it is not an access-control boundary. Any principal with dynamodb:SearchVectors on the index can submit another tenant’s partition-key value, and fine-grained LeadingKeys conditions do not apply to this API. For strict tenant isolation, use separate tables or indexes with separate IAM grants; still enforce the tenant value in your application authorization path.

So when does this actually replace your vector DB?

Reach for DynamoDB native vector when:

DynamoDB is already your operational store and the vectors describe rows you already keep there. This is the whole point. The win is deleting a pipeline, not gaining a better index.
Your dominant query is “give me the similar items and their data” in one shot. Returning the row with the match is where this earns its keep.
You want per-tenant isolation and throughput and a partition key maps cleanly onto your tenant boundary.
You want one bill and no second thing to operate.

Do NOT reach for it when:

You need a full managed RAG pipeline. DynamoDB gives you vector search. It does not give you document chunking, an ingestion pipeline, or a retrieve-and-generate orchestration. If you want that turnkey, Bedrock Knowledge Bases is still the fast path, and you would be rebuilding its plumbing by hand.
Recall has to be near-exact over a modest corpus. ANN plus a tuned dedicated index (OpenSearch) will beat a general-purpose store on recall quality. Measure on your own golden set before you commit, this is the one number that quietly decides the migration.
Your source of truth is not in DynamoDB. If the data lives in S3 or Postgres, adding DynamoDB just to hold vectors reintroduces the exact sync problem this feature removes, pointed the other way.

Pitfalls

“Vector search” is not “RAG.” The feature returns nearest items. Chunking, embedding orchestration, and generation are still yours to build. Do not scope a project as “we’ll use DynamoDB instead of a RAG stack” without accounting for the parts it does not do.
Dimensions are fixed at index creation and must match the model. Switching embedding models later (different dimension) means a new index and a backfill. Pin your model choice deliberately.
KEYS_ONLY projection quietly brings back the round trip. If you set it to keep the index small, you are back to a second GetItem per hit. Use INCLUDE with just the fields the result view needs.
The read API is not Query or Scan. Vector indexes are readable through SearchVectors only. Results are capped at 16 MB with no pagination, so a wide ALL projection plus a high TopK can exceed the response limit; narrow the projection or reduce TopK for large items.
Measure recall, not vibes. ANN trades exactness for speed. A demo that looks great on ten queries can miss on the long tail. Build a golden set of query-to-expected-result pairs and check recall against your current store before migrating.

What to actually do

If you already run DynamoDB as your operational database and you have been eyeing a bolt-on vector store, prototype this first. Add a vector index to a copy of the table, embed a slice of your data, and run your real queries against it with a golden set to check recall. If recall holds, you delete an entire database, a sync pipeline, and a round trip. If it does not, you learned that cheaply, and the dedicated-store options in the decision guide are still there.

The mental shift is the same one that post ended on: the question stopped being “which vector database” and became “do I need a separate one at all.”

Using AgentCore Identity Without a Shared Client Secret

Yoonsoo Park — Thu, 30 Jul 2026 09:00:00 -0400

Consider a customer-support agent that needs to read a customer’s order history from an internal orders API. The API is protected by an identity provider (IdP), so the agent needs an access token before it can make the request. To obtain that token, it first has to authenticate itself to the IdP.

This authentication step is the focus of this post. In July 2026, AWS added Private Key JWT client authentication to Amazon Bedrock AgentCore Identity, providing an alternative to shared client secrets. The current AgentCore configuration docs are the source of truth for supported algorithms, key policy, and regional placement.

Where Identity fits in AgentCore

When an agent needs to call a protected downstream resource, it asks AgentCore Identity for a token:

agent → GetResourceOauth2Token → (access token) → orders API

AgentCore Identity authenticates with the IdP’s token endpoint, obtains an access token, and returns it to the agent. The agent then uses the token to call the orders API.

The important detail is how that authentication works. Before the IdP issues a token, the client, in this case AgentCore Identity acting for the agent, must prove its identity.

Before: the shared client secret

A traditional OAuth 2.0 client-credentials setup uses a shared secret. You register the agent as a client with the IdP, receive a client_id and client_secret, and store the secret. AgentCore Identity sends both values when it requests a token:

POST /token
grant_type=client_credentials
client_id=support-agent
client_secret=SUPER_SECRET_VALUE ← the shared string

The approach works, but it leaves you responsible for a long-lived credential. The secret must be stored somewhere, such as Secrets Manager, an environment variable, or a configuration store. Both parties retain a copy, and anyone who obtains it can impersonate the agent. That creates several operational problems:

Storage: The secret has to be protected and audited wherever it is stored.
Rotation: The value must be changed at the IdP and in your own store without interrupting requests.
Exposure: Anyone with the secret can request tokens as the agent, and the IdP cannot distinguish that request from a legitimate one.
Scale: Each new agent or integration adds another secret to store and rotate.

The limitation comes from the symmetric trust model: both sides hold the same value, so possession of the secret is enough to authenticate.

After: Private Key JWT

Private Key JWT replaces the symmetric secret with an asymmetric signature. You generate a key pair, register the public key with the IdP, and keep the private key in AWS KMS.

The token request then works as follows:

The agent calls GetResourceOauth2Token on AgentCore Identity.
AgentCore Identity reads the credential provider configuration (client ID, KMS key ARN, and signing algorithm), creates a short-lived JWT client assertion, and calls kms:Sign with the KMS key.
KMS signs the assertion and returns the signature. The private key remains in KMS.
AgentCore Identity posts the signed assertion to your IdP’s token endpoint with grant_type=client_credentials and client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer.
The IdP verifies the signature against the public key you registered and returns an access token.
AgentCore Identity returns the token to the agent, which uses it to call the orders API.

The agent and downstream API do not change. Only the client-authentication step changes: instead of sending a shared secret, the client proves that it can use the private key without extracting or transmitting it.

The difference is also visible in the credential provider configuration. With a shared secret, the sensitive value is part of the configuration:

client_id: support-agent
client_secret: SUPER_SECRET_VALUE ← the thing you must guard

With Private Key JWT, the configuration points to a KMS key, and IAM controls who can use it. The KMS key must be in the same Region as the credential provider (cross-account use is supported when the key policy allows it):

client_id: support-agent
kms_key_arn: arn:aws:kms:us-east-1:111122223333:key/....
signing_alg: ES256 ← no private key in the config

This addresses many of the operational problems of a shared secret:

Storage: The private key stays in KMS; the configuration stores only its ARN.
Rotation: You can create a new key, register its public key, and then retire the old one without copying private key material.
Exposure: A leaked key ARN is not sufficient to authenticate without kms:Sign permission.
Scale: Each agent can have its own key, policy, and audit trail.

Choosing a grant flow

Private Key JWT authenticates the client. It does not determine whose identity the resulting token represents. AgentCore Identity supports three grant flows, and the right choice depends on who the agent is acting as:

Machine-to-machine (M2M): The agent acts as itself, without a user identity. It uses the client_credentials grant, and the token subject is the client. The example in this post fits this flow because the order-history lookup is a service-level operation.
On-behalf-of (OBO): The agent acts for a specific user who already has a token. AgentCore Identity exchanges the incoming user token for a downstream token (RFC 8693 token exchange or the RFC 7523 JWT authorization grant) while authenticating the client with its assertion.
User-delegated access: The agent acts for a user who does not yet have a token. The user completes an interactive sign-in and consent flow (a three-legged authorization-code flow) before the agent can act.

If the support agent had to read data using the customer’s own identity and permissions, OBO would be a better fit. For a service-level lookup, M2M is appropriate. Private Key JWT can authenticate the client in all three flows.

Details to check

The signing algorithm must match across three systems. The algorithm required by the IdP must be supported by AWS KMS and AgentCore Identity, and it must match the credential provider configuration. The available options are RS256, PS256, and ES256, with a compatible KMS key specification. The AWS example uses ECC_NIST_P256 with ES256. Choose the algorithm first, then create a KMS key that supports it. A mismatch typically appears as a verification failure at the token endpoint rather than during key creation.

Restrict the key with kms:ViaService. Grant kms:Sign and kms:DescribeKey in the KMS key policy as required by the provider, but constrain use with a kms:ViaService condition for bedrock-agentcore-identity.<region>.amazonaws.com. This limits signing to requests made through AgentCore Identity, even if another principal has a broad KMS permission.

Choose where the key pair is generated. You can create the key pair in KMS and send the public key to the IdP (kms:GetPublicKey), or generate it at the IdP and import the private material into KMS (kms:GetParametersForImport and kms:ImportKeyMaterial). Generating the key in KMS keeps the private key non-exportable from the start and is preferable unless the IdP requires the second approach.

Audit signing calls in CloudTrail. Each kms:Sign call made by the credential provider is recorded in CloudTrail. These events provide a record of when and under whose request the key was used. A shared secret reused outside your environment does not provide the same visibility.

Migration guidance

For an existing credential provider that uses a shared client secret, migration requires a KMS key, public-key registration at the IdP, and a credential provider configuration change. The main benefit is removing a long-lived shared secret from the authentication path.

For new integrations, Private Key JWT is a sensible default when the IdP supports it. It lets the client authenticate with a signature while keeping the private key inside KMS, reducing both secret-management work and the risk of credential exposure.

Charters and Plumbing: Why AI Coding Guidelines Always Sound Generic

Yoonsoo Park — Sat, 18 Jul 2026 09:05:00 -0400

Every org is publishing AI coding guidelines now. They all look about the same. Quality over quantity. Keep PRs small enough that a human can actually review them. Don’t use agents as a replacement for human review. We are each responsible for every line we submit. We critically evaluate AI outputs.

All correct. Nothing to argue with. And that’s the problem.

Correct and enforced are not the same thing

“We are responsible for every line” is a pledge, not an enforcement. “We critically evaluate AI outputs” is fine, but evaluate with what? How do you verify “we take pride in our craftsmanship”? You can’t. A sentence you can’t measure, however right, ends up as a framed poster on the wall.

These documents usually are what they are: not a document that grants new capability, but one that prevents accidents. That’s not a knock. As a charter that aligns culture and blocks the worst outcomes, it does its job. The trouble starts when you mistake the charter for the plumbing.

A loop can hit its stopping condition and still be wrong

I saw that line in a public agent-stack builder’s guide. A loop can meet its stopping condition and still produce the wrong result. Every test can be green while not a single test actually passed. Two reviewers can both click approve, and that approval is an opinion, not evidence.

So good systems don’t appeal to a person’s conscience. They write facts into the environment. The gate is a script, not a meeting. “Done” is defined as “a passing test row exists in the database,” not “a reviewer clicked green.” A verdict is an opinion; a row is evidence. Mix the two and the lower layer hands the upper layer a summary instead of a fact, and the upper layer closes on top of a lie.

One more thing. Make models of the same lineage review each other and they share blind spots. Wherever the writer is wrong, a reviewer from the same family misses it in exactly the same way. Review should come from a different lineage when you can manage it. If the grader and the answer-writer run on the same brain, that isn’t grading.

You can’t save cost with a pledge either

The one solid section in any of these guidelines is always the cost section. Route simple tool calls to a cheaper model. Turn on prompt caching. Keep your model tiers in one place instead of scattered per project. The most expensive model isn’t required for every task. These aren’t advice, they’re switches. Flip them and the bill drops.

That’s the difference from the rest of the virtues. Cost rules are verifiable. Whether the cache broke, whether the cheap model actually handled the tool call, you can read that off the logs. Only measured rules get followed. The rest are just hoped for.

A caution here. You often see a blanket rule: never spawn subagents. That’s an overcorrection. The real problem isn’t subagents, it’s that a child inherits the parent’s effort level, so the whole fleet runs at max cost and burns the context window in one shot. The thing to control is effort and a budget cap, not “don’t.” Forbidding a tool and capping a tool’s cost are different moves.

So what do you actually do

This isn’t a case against guidelines. You need a charter. It sets direction and blocks the worst outcomes. But after you read the whole thing, ask yourself one question per line: if I betray this sentence, what stops me? If nothing stops you, it isn’t a guideline, it’s a wish.

One gate that refuses to pass when there’s no passing test, even with the light green, keeps a team more honest than ten virtues you can’t measure. Listing good values and making those values impossible to betray are completely different jobs. Most orgs stop at the first one.

Everyone already has the charter. What’s always missing is the plumbing.

WAF Comes to AgentCore Gateway: Perimeter Security for the MCP Front Door

Yoonsoo Park — Thu, 02 Jul 2026 09:05:00 -0400

If you expose an agent to the outside world, the scary part isn’t the model. It’s the front door. The gateway that fans a single request out to a dozen MCP tools, a memory store, and downstream integrations is the highest-leverage thing an attacker can hit. One malformed or abusive request there touches everything behind it.

In June 2026 AWS made AWS WAF generally available for Amazon Bedrock AgentCore Gateway. This is a small announcement with an outsized architectural implication: the perimeter for agentic workloads now sits at the gateway, where it belongs.

Why the gateway is the right control point

AgentCore Gateway is the MCP front door. A caller hits the gateway, and the gateway routes to whatever tools, agents, and integrations sit behind it. That fan-out is exactly why it’s the correct place to enforce protection:

One config, everything covered. A single Gateway-level WAF association protects all downstream tools and integrations at once. You don’t bolt WAF onto each tool.
It’s where abuse concentrates. Rate abuse, bot traffic, and known-bad payloads all funnel through the same entry point. Defend the funnel, not each cup.
It’s the trust boundary. Everything upstream of the gateway is untrusted; everything downstream you built. That’s the definition of a perimeter.

Before this, securing that boundary meant custom infrastructure in front of the gateway. Now it’s a managed association.

What you actually get to turn on

The announcement lists concrete capabilities. Mapped to what they defend against:

Control	What it stops
IP-based access controls	Callers from where you don’t do business
Rate-based rules	A single client hammering the gateway (cost + DoS)
Managed Rule Group: Bot Control	Automated scraping and abuse traffic
Managed Rule Group: Known Bad Inputs	Payloads matching published exploit signatures
WAF protection packs	A curated bundle applied consistently

Available in every region where both WAF and AgentCore Gateway are supported, so unlike some launches this isn’t gated to a handful of regions.

The association is regional: one regional web ACL protects a gateway, and the web ACL and gateway must be in the same Region. AWS documents FAIL_CLOSE as the default WAF integration behavior; FAIL_OPEN is an explicit availability tradeoff. Watch the WafBlocks, WafFailOpens, and WafFailCloses metrics when you roll this out.

The decision tree: which rules, when

Turning everything on is not the goal. Each rule has a false-positive cost, and agent traffic is weirder than normal web traffic. Here’s how I’d sequence it.

Rate-based rules first, always. The cheapest, highest-value control. An agent gateway with no rate limit is a cost incident waiting to happen, before you even get to security. Set a ceiling that’s generous for real clients and lethal for a runaway loop.
IP controls if your caller set is knowable. Internal or partner-only gateway? Allowlist the org’s ranges. Public gateway? Skip the allowlist, it’ll just cause pages.
Known Bad Inputs, in count mode first. Turn it on counting, not blocking, watch for a week. Agent payloads (big JSON, tool schemas, embedded code) can trip signatures written for web forms. Promote to block only after you’ve confirmed the false-positive rate.
Bot Control last, and carefully. Legitimate agent-to-agent (A2A) traffic can look exactly like a bot, because it is one. If your gateway serves other agents, Bot Control can shoot your own callers. Scope it or leave it off.

The theme: the more an agent gateway is used by other machines, the more the “block bots” instinct works against you. Web WAF assumes humans are good and bots are bad. Agent WAF can’t.

Pitfalls

WAF is perimeter, not authorization. It blocks abusive traffic shapes. It does not decide whether an authenticated caller is allowed to invoke a specific tool. You still need real authz at the gateway (scoped roles, OAuth, tool-level permissions). WAF in front, authz inside.
Count mode before block mode, every managed rule. The single most common WAF self-inflicted outage is enabling a managed group in block mode and discovering it eats legitimate traffic. Agent payloads make this worse. Count, observe, then block.
Rate limits need a per-client key, not just per-IP. Many agents call through NAT or a shared egress, so per-IP rate limiting can lump distinct tenants together. If you can key on an auth identity, do it.
Don’t let WAF become your only layer. A gateway WAF is one ring. The downstream tools still need input validation and least privilege. Perimeter security that assumes the inside is safe is how one bypass becomes total.

What to do

If you run an AgentCore Gateway that anything outside your own account can reach, associate a WAF, and start with a rate-based rule today. That one control alone closes the most likely incident (a runaway or abusive client). Then walk the rest of the tree in count mode. And keep the framing straight: WAF secures the shape of traffic hitting the front door. It is not a substitute for deciding, inside the gateway, who’s allowed to open which door.

Where Do You Run Agent-Generated Code? Lambda MicroVMs and the Isolation Tradeoff

Yoonsoo Park — Thu, 02 Jul 2026 09:00:00 -0400

If you build agents, you eventually hit the question nobody wants: the model just wrote some code, and now something has to run it. Not your code. Code the LLM generated a second ago, possibly wrong, possibly hostile if a prompt injection got through. Where does that run?

In June 2026 AWS introduced Lambda MicroVMs, a compute primitive built for exactly this. The Lambda MicroVM documentation is the source of truth for limits and regional availability; those details are moving quickly.

The three things you want and can’t all have

When you run untrusted code, you want three properties at once:

Isolation so a bad process can’t read another tenant’s data or escape into your infra.
Speed so the agent doesn’t stall for seconds every time it runs a snippet.
State so a long task can pause, keep its working directory and memory, and resume later.

Historically you picked two. A shared container is fast and stateful but the isolation is a namespace, not a wall. A fresh Firecracker microVM per request is isolated and fast to boot but throws away all state. A full EC2 VM is isolated and stateful but nowhere near instant.

Lambda MicroVMs are AWS’s claim that you can now have all three. It’s the same Firecracker tech underneath Lambda (the announcement cites 15+ trillion invocations a month), but exposed as a primitive you launch directly.

What it actually gives you

The concrete capabilities, stripped of marketing:

VM-level isolation for multi-tenant execution, without you managing any virtualization layer.
Near-instant launch, plus suspend and resume for up to 8 hours. This is the interesting part. A microVM can hold a paused task, and you resume it later instead of rebuilding context.
Images from a Dockerfile, launched with a dedicated HTTPS URL that speaks HTTP/2, gRPC, and WebSockets.
Pay for baseline while running, plus whatever you consume above baseline.

The suspend/resume window is what separates this from “just a fast sandbox.” An agent that runs a multi-step task, waits on a human approval, then continues, can now sit in a suspended microVM instead of holding a container open or serializing its whole state to disk and rehydrating.

The decision: do you actually need this?

This is the part that matters. Reaching for microVM isolation when a lighter option would do is over-engineering. Here’s how I’d decide.

Situation	What to reach for
Agent runs short, pure-compute snippets you generated and control	A managed Code Interpreter sandbox. Don’t build infra.
Untrusted / model-generated code, multi-tenant, needs network or filesystem	Lambda MicroVMs. This is the case they built it for.
Long task that pauses on human approval then resumes	Lambda MicroVMs, for the suspend/resume window.
Trusted code, your own logic, just needs to scale	Plain Lambda or a container. Isolation is already fine.

The signal that you need real VM isolation is not “I’m running code.” It’s “I’m running code I did not write, on behalf of tenants who don’t trust each other.” If that sentence isn’t true, a managed sandbox is cheaper and simpler.

Pitfalls I’d watch for

Isolation is not a license to skip input handling. VM-level isolation stops an escape. It does not stop the agent from cheerfully running rm -rf on the data volume you mounted, or exfiltrating a secret you passed in as an env var. Isolation contains blast radius; it doesn’t decide what’s inside the blast.
Suspension is not the same as running. A suspended microVM preserves memory and disk and incurs snapshot-storage charges; baseline compute is charged while it is running. Terminate work you no longer need, and track suspended snapshots as well as active VMs.
Regional availability has already changed. The initial five regions expanded to ten on August 19, 2026: N. Virginia, Ohio, Oregon, Tokyo, Ireland, Mumbai, Singapore, Sydney, Frankfurt, and Stockholm. Check the current regional capability before designing around a region.
HTTPS-URL-per-microVM changes your network model. Each VM gets its own endpoint. That’s convenient, but it’s also a lot of ephemeral surface. Front it, log it, and don’t let those URLs leak into agent-visible context where a prompt injection could target them.

What to do

If you run agents that execute code they generated, write down which of the four rows above you’re actually in. Most teams are in row 1 or row 4 and don’t need a microVM. The teams that genuinely need it, multi-tenant execution of untrusted code with pause/resume, now have a primitive built for the job instead of a pile of Firecracker glue. Pick based on the isolation you actually need, not the isolation that sounds safest.

When Google Standardizes the Thing You Built Anyway

Yoonsoo Park — Mon, 22 Jun 2026 18:30:00 -0400

For the last several months I’ve been building knowledge-base agents that do something slightly heretical. Instead of standing up a vector store, chunking documents, and running similarity search at query time, the agent reads source material once and compiles it into a wiki. A directory of markdown files with YAML frontmatter, cross-linked, with an index and a change log. When a downstream agent needs to answer a question, it reads the wiki the way a person would: open the index, follow the links, read the pages.

It worked well. Better than the RAG pipeline it replaced, for the kind of slow-changing structured knowledge I was dealing with. But it always nagged at me. Vector RAG is what everyone writes blog posts about. It’s what the frameworks assume. My markdown-wiki thing felt like a toy I’d built in a corner, a clever hack that no serious team would adopt. I kept waiting for someone to tell me I was doing it wrong.

Then Google published the Open Knowledge Format. The initial v0.1 article is not the end of the story: Google published OKF v0.2 on July 24, 2026 with additive trust and provenance signals.

Review note (2026-08-28): The examples below describe the v0.1 shape. In v0.2, type remains the only required field, while optional generated, verified, sources, status, stale_after, and attestation vocabulary lets consumers judge provenance, freshness, lifecycle, and computation. timestamp is superseded by generated.at, and the body citation list is superseded by sources; v0.1 bundles remain valid.

What OKF actually is

OKF is an open, versioned specification from the Google Cloud knowledge-catalog project. The v0.1 baseline is a knowledge corpus represented as a directory of markdown files with YAML frontmatter, and that’s it. No schema registry. No central authority. No required SDK. The v0.2 additions are optional vocabulary, not a mandatory runtime or service. The spec’s own line is “if you can cat a file, you can read OKF; if you can git clone a repo, you can ship it.”

The structure is almost embarrassingly small:

Every concept is one markdown file. The file path minus .md is its ID.
Each file has a frontmatter block. Exactly one field is required: type. Everything else (title, description, resource, tags, and the v0.1 timestamp field) is recommended but optional; v0.2 uses generated.at for that timestamp.
index.md is a reserved filename for a directory listing. log.md is reserved for a change history. Both are optional.
Links between concepts are plain markdown links. A link from A to B just asserts “these are related.” The kind of relationship is left to the surrounding prose. Consumers treat every link as an untyped directed edge.
Broken links are allowed. The target might be knowledge that hasn’t been written yet.

That’s the v0.1 baseline. The conformance rules remain permissive in v0.2: a bundle is conformant if its non-reserved markdown files have parseable frontmatter and every frontmatter has a non-empty type; the new trust fields are opt-in. Consumers are explicitly forbidden from rejecting a bundle over missing optional fields, unknown types, unknown keys, broken links, or a missing index. The format is built to stay useful while it’s half-written and partially machine-generated, which is exactly the state most real knowledge ends up in.

And the spec names its inspirations directly. Section 10 lists “LLM wiki repos” and “metadata as code” as the patterns OKF is intentionally close to. That was the sentence that made me sit up. The thing I’d been quietly building was, word for word, one of the named reference patterns for an emerging open standard.

Why a directory of files beats a vector store for some jobs

The instinct in 2026 is that RAG means embeddings and a vector database. For a lot of problems that’s correct. If your corpus is huge, unstructured, and you need fuzzy recall over millions of chunks, you want a vector store.

But vector RAG rediscovers your knowledge from scratch on every single query. It pulls the top-k chunks that are similar to the question and hands them to the model, and the model has to re-synthesize an answer, re-resolve contradictions, and re-trace relationships every time. The knowledge never compounds. The retrieval is only as good as the chunking, and the chunking throws away the structure that made the source coherent in the first place.

A compiled wiki inverts that. You pay the synthesis cost once, at write time. Cross-references are already there. Contradictions have already been flagged and reconciled by whoever (or whatever) wrote the page. The relationships between concepts are encoded in the link graph, not reconstructed from cosine similarity. When the consuming agent reads a page, it gets the curated view, not a bag of nearest-neighbor fragments.

So the decision is less “RAG vs not RAG” and more about the shape of your knowledge:

Slow-changing, structured, relationship-heavy knowledge (a data model, a set of internal systems, a domain ontology): a compiled wiki wins. The structure is the value, and the wiki preserves it.
Huge, fast-changing, unstructured corpora (a support ticket history, a sprawling document hoard): vector RAG wins. You can’t hand-compile a million tickets, and you don’t need the relationships.
The honest answer for a lot of internal tooling is “both”: a small curated wiki for the structured core, vector search over the long tail.

The wiki approach also has a property that matters more than it sounds: a human can read it. It’s just markdown in git. You get diffs, attribution, code review, and the ability to open it in Obsidian and look at the graph. A vector store is an opaque blob of floats. When the agent gives a weird answer, you can open the wiki page and see exactly what it read.

The conformance cost was basically zero

Here’s the part that turned the nagging feeling into something useful. I checked my existing wikis against the OKF conformance rules to see how far off I was.

I was off by about two lines.

My wiki generator was already emitting markdown files with YAML frontmatter, organized into a directory tree, with cross-links and a machine-readable index. The only thing the spec strictly requires that I wasn’t doing was the type field in frontmatter. Adding it is one line in the generator’s frontmatter dict. The other gap was cosmetic: I had a machine-readable index.json but not the spec’s index.md, so I generate both now. The query library that consumes the index never noticed, because index.md and type are additive surface for external consumers, not changes to my runtime.

Everything else lined up on its own. My cross-links were Obsidian-style [[wikilinks]] rather than the spec’s [text](/path.md), but OKF treats links as soft guidance and never rejects a bundle over link format, so I kept the wikilinks (my reader parses them) and the bundle is still conformant. Untyped edges, permissive consumption, frontmatter-per-document: I’d arrived at the same design decisions independently, because they’re the decisions the problem pushes you toward.

Pitfalls I’ve actually hit

Running this pattern for real surfaced a few things the spec doesn’t warn you about:

Duplicate pages are the default failure mode. If the agent doesn’t check the index before writing, it creates a second page for an entity that already exists under a slightly different name. The fix is a hard rule: orient first, search the index, then write. The wiki degrades into a pile the moment you skip this.
Orphan pages are invisible. A page with no inbound links might as well not exist, because nothing will ever traverse to it. Every new page needs at least a couple of inbound links from existing pages, or it’s dead weight.
The index and the log are the navigational backbone, not bookkeeping. It’s tempting to skip updating them. Don’t. The index is how everything gets found; a stale index means real pages become unreachable.
Broken links are fine until they’re not. The spec is right that a broken link can mean “not written yet.” But you still want a lint pass that distinguishes intentional forward-references from typos, or the graph slowly rots.

What I actually got out of this

The practical win is small and concrete: a couple of lines in a generator and I can describe my knowledge bases as OKF-conformant instead of as a bespoke hack. When I explain the design to someone now, I have a reference to point at.

The bigger thing is the feeling going away. I’d been carrying this low-grade doubt that the markdown-wiki approach was a toy, that I’d taken a wrong turn while everyone else went vector. It turns out the intuition was pointing the same direction Google is now standardizing, including the trust signals an agent-written corpus needs. The pattern wasn’t a hack. It was an early implementation of something that was going to get a spec eventually.

That’s worth writing down, if only as a note to self: when a simple design keeps working and you can’t find the standard it conforms to, sometimes the standard just hasn’t been written yet. Build the simple thing, but track the spec version and add trust signals before agents write at scale.

Owning the Learning Loop

Yoonsoo Park — Mon, 15 Jun 2026 14:14:50 -0400

There’s a line in Satya Nadella’s recent essay that I haven’t been able to put down:

You can offload a task, or even a job, but you can never offload your learning.

He frames the future of the firm around two kinds of capital. Human capital is the knowledge, judgment, and pattern recognition of your people. Token capital is the AI capability you build and own. His argument is that human capital doesn’t shrink as token capital grows. It gets more valuable, because without human direction you just have “compute running in circles.”

I want to take that one rung down the ladder, from the firm to the individual, because I’ve been living a small version of it for months and the framing finally gave me the right words.

The model is rented. The learning is bought.

Here is the uncomfortable part of building on top of someone else’s frontier model: the model is not yours. It can be deprecated, repriced, rate-limited, or quietly swapped for a worse checkpoint on a Tuesday. Every capability you depend on inside that model is borrowed.

So if the model is rented, what do you actually own?

You own whatever you accumulate around the model. The corrections you fed it. The evals that encode what “good” means for your work specifically. The traces of every task it got right and every task it botched. The knowledge base that turns six months of context into something queryable instead of something you re-explain every morning.

That accumulation is the learning loop. And unlike the model, it’s yours. Nadella calls it the firm’s new IP and describes it as a hill-climbing machine that compounds. At the scale of one person, it’s the difference between an assistant that resets to zero every session and one that actually becomes a veteran of your work.

What owning the loop actually looks like

The temptation is to treat “owning your AI” as picking the best model. That’s the wrong layer. The model is the commodity. The loop is the asset. Concretely, the loop is three things sitting on top of whatever model you happen to be renting this quarter:

Private evals. Not MMLU, not someone’s leaderboard. Evals that measure whether the thing is getting better at the outcomes you care about. For me that’s “did it correctly reconstruct the state of a project I haven’t touched in two weeks,” not “did it score well on a public benchmark.” If you can’t articulate your own definition of good, you’re outsourcing your standards to whoever made the benchmark.

Real traces from real use. Every session is a training signal if you keep it. The tasks the agent fumbled are worth more than the ones it nailed, because they’re where the loop has room to climb. The point isn’t to fine-tune a model tomorrow. It’s that the raw material for improvement is being captured instead of evaporating.

A queryable institutional memory. This is the one most people skip, and it’s the one that compounds hardest. A knowledge base, even a directory of plain Markdown notes, turns “what did we decide about X three months ago” from a re-derivation into a lookup. Institutional memory you can query is the difference between a tool and a colleague.

None of this requires owning a model. It requires owning the context around the model, and keeping it persistent.

The real test: swap the model, keep the veteran

Nadella has a sharp way of stating the test:

A company should be able to switch out a “generalist” model without losing the “company veteran” expertise built into their learning system.

That’s the whole thing in one sentence. Sovereignty isn’t “I run my own model.” Sovereignty is “I can throw out the model I’m using and the veteran survives.” If swapping models nukes everything your system knows about your work, you never owned anything. You were just a tenant in someone else’s capability.

This reframes the commoditization fear, too. The anxiety that “AI is going to absorb my expertise and sell it back to everyone” is real, but it’s aimed at the wrong target. What gets commoditized is static knowledge, the stuff that’s already in the training set. What doesn’t commoditize is a compounding loop fed by traces nobody else has: your decisions, your corrections, your context. The defense against being commoditized isn’t to out-know the model. It’s to own a loop the model can’t see.

Pitfalls I’ve actually hit

This is where the philosophy meets the floor. Things I learned by getting them wrong:

Persistent beats volatile, every time. An agent that’s brilliant for one session and amnesiac the next is not a veteran. It’s a very expensive intern who quits every night. The single highest-leverage decision is making the loop survive the session. If your accumulated context isn’t written down somewhere durable, you don’t have a loop. You have a goldfish.
A knowledge base you don’t maintain is a liability, not an asset. Stale notes are worse than no notes, because they actively mislead. The loop only compounds if you prune as well as append. I treat outdated context like a leak, fix it the moment I notice it, not “later.”
Keep the loop outside the model. The instinct to lean on a single vendor’s memory feature or fine-tune is a lock-in trap. The moment your learning lives inside one model’s weights or one platform’s proprietary store, you’ve failed the swap test. Keep evals, traces, and knowledge in formats you control and can carry to the next model.
Don’t confuse activity with accumulation. Running a thousand tasks and saving nothing is not a loop. It’s a treadmill. Compounding requires that each task leave a deposit. If nothing is being written back, you’re just generating tokens, not capital.

What you should do

Start owning your loop now, at whatever scale you operate. You don’t need a frontier model or an RL pipeline. You need three habits:

Write down your own definition of good. A handful of cases that matter to you, that you can re-run. That’s your private eval, version zero.
Make the context persistent. A notes directory, a memory file, anything durable that survives the session. The bar is “tomorrow it remembers what today decided.”
Prune as ruthlessly as you append. The asset isn’t volume. It’s a loop that stays true.

Nadella’s worry is that a few models capture all the value while everyone else’s knowledge gets commoditized out from under them. The defense, at every scale, is the same: own the learning loop. The model is the thing you rent. The loop is the thing you keep.

OpenSearch Serverless NextGen: Does Scale-to-Zero Actually Change RAG Costs (And What It Doesn't)

Yoonsoo Park — Tue, 09 Jun 2026 02:30:00 -0400

AWS rebuilt Amazon OpenSearch Serverless for agentic AI workloads. The headline numbers are real and worth your attention: idle collections can now scale compute down to zero, burst up to 20x in seconds, and the blog claims up to 60% cost savings versus the previous capacity model. Check the current collection-generation documentation before applying the migration steps.

If you run a RAG stack — especially one where OpenSearch Serverless sits behind a managed knowledge base as the vector store — this lands right in your cost center. But I spiked the migration, and the interesting part isn’t the savings. It’s the gap between what the announcement promises and what the migration actually costs you. Let me separate the two decisions that this announcement tends to collapse into one.

What the announcement actually says

Strip the marketing and NextGen is an economics and elasticity change, not a new retrieval feature:

Scale-to-zero. The old model kept a floor of OCUs (OpenSearch Compute Units) running per collection — you paid for that floor even when traffic was zero. NextGen lets indexing and search compute drop to zero on idle. You pay storage, not idle compute.
Instant 20x burst. When traffic returns, capacity scales back up in seconds rather than minutes.
Up to 60% cheaper for spiky or low-duty-cycle workloads — which describes almost every internal or dev/QA RAG environment.

What it is not: a better retriever, a new ranking model, a new connector, or anything that changes the quality of what your RAG returns. This is a bill optimization for the vector layer. Keep that framing — it matters for the second half of this post.

The migration trap the blog skips

Here’s what I found spiking the actual CloudFormation change. NextGen isn’t a flag you flip on an existing collection. The way you express “NextGen” in CloudFormation is by attaching a collection to a new AWS::OpenSearchServerless::CollectionGroup resource — the group carries CapacityLimits where you set min OCU to 0 for indexing and search (that’s your scale-to-zero knob), plus a max ceiling.

The trap: the property that links a collection to its group is Update requires: Replace.

That single line in the CFN docs changes the whole story. Attaching an existing collection to a group doesn’t reconfigure it in place — CloudFormation deletes and recreates the collection. Which means:

Your vector index is gone and must be rebuilt.
If a managed knowledge base (e.g. Bedrock Knowledge Bases) consumes that collection, you re-ingest the entire corpus into the fresh collection.

So this is not “a one-line config change.” It’s “a new collection plus a full re-index.” For an internal knowledge base where the source documents live elsewhere, there’s no data-loss risk — but there is real re-ingestion work, multiplied by every region you run in. Budget for it. The announcement won’t.

Pitfalls I actually hit

aws-cdk-lib already has the L1. I assumed I’d need a CDK upgrade to get CfnCollectionGroup and the collectionGroupName property. I didn’t — a recent-but-not-bleeding-edge aws-cdk-lib already exposes both. Check your installed version before you bump it; you may already be there.
Generation is explicit. A collection group accepts Generation: NEXTGEN (or the CLI’s --generation NEXTGEN); the collection then inherits that generation through its group. It is not a flag you can add to an existing Classic collection in place.
cdk synth passing is not validation. I got a clean synth producing valid CloudFormation — CollectionGroup with min 0 / max N, collection wired to it. That proves the template compiles. It proves nothing about whether your downstream consumer accepts the new collection at runtime. (More on this below.)
Type-available is not deploy-validated. I confirmed the CollectionGroup resource type is available across all the major regions I care about. That removes regional availability as a blocker — but “the API knows about the type” and “I deployed it and the knowledge base indexed against it” are two different gates. Don’t let the first one let you skip the second.
Scale-to-zero trades against cold start. Zero idle compute is free money for dev/QA, where nobody’s waiting. On a customer-facing path, the first query after idle pays a warm-up. Whether that’s acceptable is a latency conversation, not a cost one — and it’s the reason I’d gate the change to non-prod first and prove the cold-start behavior before touching production.

The decision this announcement does NOT make for you

Here’s the trap I see teams walk into. A vector-store cost announcement arrives, and it gets read as a signal to switch RAG engines — “should we move off our managed search service onto OpenSearch?”

Those are different decisions, and this announcement only touches one of them.

“Should I move my existing OpenSearch vector store to NextGen?” — Yes, plausibly. It’s a cost optimization on infrastructure you already run. The analysis is the migration cost (re-index) versus the idle-compute savings. For low-duty-cycle environments, that math is easy.
“Should I replace my managed RAG service with OpenSearch?” — This announcement is irrelevant to that question. Engine choice is about retrieval quality, relevance tuning, ACL and multi-tenant filtering parity, connector ecosystem, and operational burden. A 60% bill reduction on the vector layer tells you nothing about whether OpenSearch retrieves better for your corpus, or whether you can reproduce your current access-control model. If you’re evaluating an engine switch, evaluate those axes — and don’t let a cost headline stand in for that work.

Conflating the two is how you end up justifying a months-long engine migration with a number that was only ever about idle compute.

What you should do

If you already run OpenSearch Serverless as a vector store: spike the NextGen migration in dev. Wire a CollectionGroup with min OCU 0, attach the collection, and actually deploy it — then confirm your knowledge base re-indexes and retrieves against the new collection. Synth passing is not that proof.
Plan for re-ingestion, not a config flip. The collection gets replaced. Know your re-index cost per environment before you commit.
Gate it to non-prod first. Capture the scale-to-zero savings where idle is free, and prove cold-start latency before you put a customer-facing path behind it.
Don’t let this decide your RAG engine. If you’re weighing a managed-search-to-OpenSearch move, run the retrieval-quality and access-control evaluation that decision actually requires. This announcement isn’t input to it.

NextGen is a genuinely good change for the right workload. Just be honest about which decision it’s answering — and which one it’s quietly tempting you to skip.

Interactive Shells in Bedrock AgentCore Runtime — The Debugging Blind Spot Just Closed

Yoonsoo Park — Mon, 08 Jun 2026 02:30:00 -0400

If you run agents on Bedrock AgentCore Runtime, you already know the shape of the problem. Your agent isn’t a Lambda you can re-invoke locally — it’s a managed container (possibly in a private VPC subnet, if you configure VPC networking), holding session state you can’t see, talking to an MCP gateway and a memory store you can only observe through logs. When a session misbehaves, your entire toolbox has been: tail CloudWatch and guess.

In June 2026, AWS closed that gap: AgentCore Runtime now supports interactive shells into running agent sessions, via a new InvokeAgentRuntimeCommandShell API. You can attach a real terminal to a live session and look around.

This sounds like a developer-experience footnote. For anyone running agents as containers, it’s the difference between forensics-by-logfile and walking into the room.

Why this was a black box

The thing that makes AgentCore Runtime good in production is the same thing that made it opaque to debug:

The agent runs as a container in a private subnet — no public ingress, no SSH, no direct reach.
Session state lives inside the running process: environment variables, working directory, in-memory context, whatever the agent has loaded.
Everything you knew about a session came after the fact, from logs — and only what you remembered to log.

So when a tool call silently failed, or a cross-account role assumption didn’t fire, or the wrong context got injected into a session, you couldn’t go look. You added log lines, redeployed, and waited for it to happen again. For a class of bugs that only reproduce under specific session state, that loop is brutal.

What landed

The new API gives you a persistent, PTY-backed terminal over WebSocket. The headline capabilities:

InvokeAgentRuntimeCommandShell — opens an interactive shell into a running agent session.
Complements the existing InvokeAgentRuntimeCommand — which runs a single one-shot command and returns.
Full terminal features: colors, tab completion, Ctrl+C, terminal resize, automatic reconnect.
Persistent state across commands: environment variables, working directory, and command history survive between commands in the same shell.
Reconnectable: sessions are addressed by a runtime session ID plus a shell ID, so you can drop and re-attach to the same shell.
Up to 10 concurrent shells per agent runtime — parallel debugging across sessions.
Access via the AgentCore CLI: agentcore exec --it --runtime <runtime-arn>.

One-shot vs interactive — pick the right one

The two APIs answer different questions. Don’t reach for the interactive shell when a one-shot command would do.

	`InvokeAgentRuntimeCommand`	`InvokeAgentRuntimeCommandShell`
Shape	Single command, returns output	Persistent interactive session
State	Stateless per call	Env vars / cwd / history persist
Transport	Request/response	WebSocket (PTY)
Reconnect	N/A	Re-attach by session + shell ID
Best for	Scripted checks, CI probes, “is X set?”	Live exploration, multi-step investigation

If you’re scripting a health check or a deterministic probe, Command is cheaper and auditable. The shell is for the I don’t know what I’m looking for yet case.

When you actually reach for the shell

This isn’t an everyday tool. It earns its keep on the bugs that don’t reproduce on demand:

Verify injected configuration. Is the runtime actually seeing the gateway URL, memory ID, and account config you think you wired in? printenv inside the live session beats reading CDK output and hoping.
Diagnose connectivity from inside the network. The container sits in a private subnet. From the shell you can curl the MCP gateway endpoint, test a cross-account sts assume-role, or confirm a downstream agent (A2A) is reachable — instead of inferring failure from a stack trace.
Inspect session context. In a multi-tenant runtime, “did this session boot with the right tenant context?” is a question you’ve never been able to answer at runtime. Now you can.
Parallel investigation. Ten concurrent shells means you can pin one session, compare against a known-good one, and not lose your place when you step away — the reconnect-by-ID semantics keep the shell alive.

Pitfalls and the security conversation

A live shell into a running agent is powerful, which is exactly why it’s dangerous. Before you enable it, walk through these:

A shell into a production agent session is a privilege. It’s interactive code execution inside a process that holds real credentials, real session data, and (in multi-tenant setups) potentially other tenants’ context. Treat it like SSH-into-prod, because that’s what it is.
Gate it with IAM, not goodwill. The action that opens a shell is distinct from the action that invokes the agent. Grant InvokeAgentRuntimeCommandShell (and the one-shot Command variant) explicitly, to a small set of principals, and deny it in production unless you have a break-glass process. Don’t let it ride along on your existing invoke permissions.
Default to dev/QA. The overwhelming majority of the value is in non-prod, where you’re chasing reproductions. Enable the shell there freely; in prod, make it an audited, time-boxed exception.
Check your CLI version. agentcore exec --it needs an AgentCore CLI build that speaks the new API. Confirm before you plan a debugging session around it.
Mind the operational limits. A shell connection can last up to one hour, a frame is limited to 64 KB, and reconnecting can replay up to 256 KB of buffered output. Runtimes also have an idle session timeout (for example, 15 minutes), so know whether an attach resets that clock. CloudTrail records API metadata, not shell stdin/stdout.

What you should do

If you run agents on AgentCore Runtime, the move is small and worth making:

Add bedrock-agentcore:InvokeAgentRuntimeCommandShell (and InvokeAgentRuntimeCommand) to a dev/QA-scoped IAM policy, attached to your team’s debugging principals — not to the agent’s own runtime role.
Keep it denied in production behind a documented break-glass exception.
Confirm your AgentCore CLI supports exec --it.
The next time a session bug won’t reproduce, stop adding log lines. Attach, look, and fix.

The pattern shift is the whole story: agent debugging goes from guess-from-logs to walk-in-and-look. That’s worth a one-line IAM change and a guardrail.

Step Functions × AgentCore: What the Managed Harness Integration Actually Supports

Yoonsoo Park — Thu, 04 Jun 2026 11:30:00 -0400

AWS announced an optimized Step Functions integration for the managed Bedrock AgentCore harness in June 2026. The important detail is easy to miss: the resource is arn:aws:states:::bedrockagentcore:invokeHarness, and the integration currently supports Request Response only.

That is still useful for a state machine that already needs a managed AgentCore turn. It is not a drop-in .sync replacement for every InvokeAgentRuntime call, and it does not make an eight-hour agent invocation a single Step Functions task.

The shape we keep ending up with

If you’re building agentic features on AWS for a real product, the architecture converges on something close to this:

POST /something/runs → 202 + requestId
↓
Step Functions starts
↓
Lambda(call agent + write result)
↓
DynamoDB updated
↓
GET /something/runs/{id} → status + output

The state machine exists because the agent call is too slow to hold an HTTP connection open for. The Lambda may be thin, but it often owns session IDs, payload storage, retries, callback tokens, and the durable result. The optimized integration can remove that wrapper for a bounded harness turn, but it does not remove those workflow responsibilities automatically.

It works. It also has four specific problems that don’t go away no matter how clean your code is.

Four problems this pattern actually has

1. A task limit still decides how long the optimized turn can run

This one is backwards. The agent’s reasoning budget should be a product decision — “this action involves five tool calls and a long context, so it might take 8 minutes” — but in practice, the limit is whatever Lambda lets you do. Anything longer needs ECS, Fargate, or a chain of Lambdas that hand off state, all of which are work nobody actually wants to do.

The optimized resource is subject to the Step Functions integration limit of 15 minutes. Increasing TimeoutSeconds above that does not turn it into an eight-hour task. If the task times out, the harness can continue running, so you need an explicit cleanup or reconciliation path.

2. Multi-step agent workflows fail atomically

If your action does plan → fan-out tool calls → reduce → validate, all of that runs inside one agent loop, inside one Lambda. Any failure — a tool that timed out, a downstream service that returned 503, a model that produced malformed JSON on the third turn — restarts the whole thing.

The state machine layer above it is useless for this, because from its perspective the Lambda either succeeded or didn’t. There’s no “the plan finished but the validation step blew up, retry just the validation.”

You can still make the workflow a workflow, but you do it with separate states rather than one automatically decomposed agent call:

Plan(agent)
→ Map(tool calls in parallel)
→ Reduce(agent)
→ Validate(agent)

Each step has its own retry, catch, and checkpoint. A failure in Validate re-runs Validate, not the whole chain.

3. External job polling is a pattern everyone reimplements

Textract async, Bedrock batch inference, anything with “submit job → poll for completion” — every team writes the same loop. Configurable interval, max attempts, status mapping, exit on failure. It’s never quite the same code twice.

For AgentCore, the optimized harness task is Request Response, not a general .sync poller. If you need submit-and-wait semantics, use one of the explicit callback or direct-SDK patterns described below and keep the session, timeout, and result state in your design.

4. Agent execution is invisible at the workflow layer

Right now, if a multi-step agent call goes wrong, your CloudWatch logs are a wall of {"level": "INFO", "agent": ...} lines and you’re greping for the failure. Per-step cost? Aggregated at the Lambda level. X-Ray traces? They cover the Lambda, not the agent’s internal turns.

When the agent invocation is a state machine task, the workflow execution view shows it as a step. Cost attributes per step. X-Ray traces span the agent call. Failure modes have names again.

What the optimized AgentCore task changes

Concretely:

Before	After
Lambda wrapper calls `invoke_agent_runtime`	Optimized `arn:aws:states:::bedrockagentcore:invokeHarness` task
Lambda has a 15-minute timeout	Optimized task is also limited to 15 minutes
Agent loop is one opaque call	Separate states are still required for independent retry
Hand-written polling/callback code	Still required for long-running or callback workflows
Lambda logs only	Final text plus execution/CloudWatch harness trace link
Custom approval state	`waitForTaskToken` remains an explicit pattern outside this task

The approval case still matters, but it is not supplied by the optimized harness resource. A state machine can pause with waitForTaskToken, an external system can call back with the token, and a later state can invoke AgentCore. Keep the approval token and business state in a durable store rather than assuming the harness session is the workflow record.

Patterns for genuinely asynchronous work

When an agent must run longer than the task limit, or a human must approve a result, use an explicit callback pattern instead of treating the optimized task as durable:

Lambda dispatcher + callback token. A Lambda starts or invokes the AgentCore runtime, gives the agent a Step Functions task token, and the agent or a callback handler calls SendTaskSuccess/SendTaskFailure when the durable work finishes.
Direct AWS SDK integration. Step Functions can call arn:aws:states:::aws-sdk:bedrockagentcore:invokeAgentRuntime without a Lambda in the request path. You still own the session ID, timeout, polling/callback decision, and result persistence.
Durable function callback. A Lambda durable function can hold the orchestration and resume from a callback while each AgentCore invocation remains a bounded unit of work.

Use a stable session ID, keep large inputs and outputs in S3 rather than the 256 KB Step Functions state, and set heartbeat/timeouts that match the business operation. A session that may last days is not the same thing as a durable business process: persist process state and let Step Functions own the wait.

Decision tree — should you actually migrate?

Not every async agent call benefits from this.

✅ Worth migrating if:

You already run agents inside Step Functions via Lambda
You need a bounded harness turn and its final text/usage result in a state machine
You already run agents inside Step Functions via Lambda and want to remove only that wrapper
You can split a workflow into explicit states with independent retry
You can keep genuinely long-running or approval work in one of the callback patterns above

⚠️ Cost-first before migrating if:

You’re using a direct SDK (Strands, raw Bedrock) inside Lambda. Moving to AgentCore Runtime is its own deployment and operational change. The integration assumes you’ve already adopted AgentCore.
Your async pipeline is small (one Lambda, one DynamoDB write) and the rewrite is bigger than the win.

❌ Don’t bother if:

The agent call is short (< 1 min), single-turn, and never fails interestingly. Lambda + SDK is fine.
You don’t actually have a state machine. Adding one to use this integration is putting the cart before the horse.

Pitfalls to expect

Step Functions state size limit is 256 KB. This already affects anyone passing large documents through SF. With agent inputs/outputs in the loop, keep payloads in S3 and pass references. The integration does not relax the limit.
Do not write InvokeAgentRuntime.sync by analogy. Use the documented invokeHarness resource for the optimized integration; .sync and waitForTaskToken are not supported there.
Task timeout and agent timeout are different clocks. A Step Functions timeout can leave the harness running. Add a cancellation, idempotency, or reconciliation plan.
AgentCore Runtime region availability. As of launch, AgentCore is in fewer regions than Step Functions. If your product runs in me-central-1 or ap-northeast-1, check before you redesign. Cross-region AgentCore invocation from SF is a separate question.
Cold start moves, it doesn’t disappear. You stop paying for a Lambda wrapper, but you still need to measure AgentCore runtime behavior on a real workload.
IAM gets a new principal in the trust chain. The state machine’s execution role needs the documented AgentCore permission for the resource you call. If your platform has tag-based access controls, the state machine role needs the right tag, not just the old Lambda role.
Observability changes shape. The optimized task returns final assistant text and aggregated usage, not every tool/reasoning block. Keep the CloudWatch harness trace or your own durable evidence for detailed debugging.

What this actually means

Before this integration, many teams put a thin Lambda around every AgentCore call. The optimized task removes that wrapper for one bounded harness turn, but it does not make every runtime invocation a durable Step Functions task.

AgentCore-as-task is therefore a useful narrow contract: final-text handoff, aggregated usage, and a link to the harness trace. Long-running execution, human approval, and partial retry still belong in explicit Step Functions states and callback patterns.

If you’ve been deferring an agentic feature because “the async story is messy,” it is worth a fresh look. Just choose the optimized task only when its Request Response and 15-minute contract actually fits.

ElastiCache Just Got Durable — What That Means for RAG and Agent Orchestration

Yoonsoo Park — Wed, 03 Jun 2026 12:00:00 -0400

On June 2, 2026, AWS announced durability for Amazon ElastiCache starting with node-based Valkey 9.0. That sounds like a small line item, but it changes what ElastiCache is for. You can pick, per cluster, whether writes are durable across AZs, so some data-store workloads no longer need to use DynamoDB merely as a safety net. Read the current durability documentation for engine, eviction, and failure semantics before treating Valkey as a source of record.

This post is me thinking out loud about where that matters. I’m a backend/platform engineer whose last real cache project was Redis in n8n. Most of my recent work is AWS AI infra — RAG pipelines, agent orchestration with Step Functions, dead-letter retries. Cache patterns sit at the seam of all of those, and I want to make sure I’m not under-using them on the next project.

What actually changed

Two new write modes, on top of the existing in-memory speed:

Mode	Write latency	Data loss window	Use when
Synchronous	single-digit ms	zero (persisted to ≥2 AZs before ack)	money, identity, state you cannot replay
Asynchronous	microseconds (free)	up to 10s on AZ failure	hot path you can rebuild from a system of record
(legacy) non-durable	microseconds	everything since last snapshot	true ephemeral cache

Reads stay at microseconds in all three. The transactional log lives across multiple AZs, so failover, restart, and recovery can preserve acknowledged writes in synchronous mode. Asynchronous mode still allows up to 10 seconds of successful writes to be lost during a failure, and durable clusters can still evict TTL keys when memory is under pressure.

The headline phrase from the AWS blurb — “AI agent long-term memory, AI agent workflow state, knowledge bases for RAG applications” — is unusually direct. AWS is telling you what they expect people to build with this.

Pattern 1 — RAG semantic cache

In a vanilla RAG path, every user query embeds → searches a vector store → re-ranks → calls the LLM. The vector search and the LLM call are the two expensive steps. Both are deterministic enough to cache.

User query
→ embed (cheap)
→ semantic cache lookup by embedding similarity ← ElastiCache
hit → return cached answer (microseconds)
miss → vector store + LLM call
→ write {embedding hash : answer} back ← ElastiCache

Key shape options:

Exact key: hash of the normalized prompt. Trivial to implement, low hit rate.
Semantic key: store the embedding and approximate-match on cosine similarity above some threshold. Higher hit rate but you need a vector index inside the cache. Valkey/Redis modules support this; you can also keep a small HNSW in memory.

Why durability matters here: if your cache is ephemeral, every cluster restart cold-starts your LLM bill. Async durability is plenty — losing 10 seconds of cached answers is not a correctness problem, just a brief cost spike. Sync durability is overkill. Default async, and remember you no longer have to choose between “cache” and “real store.”

Pitfall I’d worry about: cache poisoning when the upstream RAG pipeline returns a hallucinated or stale answer once. That answer can sit in cache for the TTL and serve to other users. Always include a content-version key (model name + prompt template version + index version) so a deploy invalidates without manual flush.

Pattern 2 — Agent workflow state in Step Functions

Step Functions gives you Map, Parallel, Wait, retry policies, and .waitForTaskToken for human-in-the-loop. What it doesn’t give you cheaply is:

Mid-execution scratchpad bigger than the 256 KB state payload
Cross-execution memory (“this agent already saw this customer last hour”)
Fast lookups that aren’t worth a DynamoDB round trip

Pre-durability ElastiCache solved the speed problem but felt risky for anything you couldn’t reconstruct. With durable Valkey, the pattern becomes clean:

Execution scoped state (lives for one Step Functions run): key agent:exec:<exec-arn>:<slot>, TTL = max execution duration + buffer. Use sync writes if losing the slot would corrupt downstream steps; async otherwise.
Agent long-term memory (lives across runs): key agent:user:<user-id>:facts, no TTL or a long one. Sync writes — this is the memory the user expects to persist.
Tool-call cache (idempotency for expensive tools): key tool:<tool-name>:<arg-hash>, short TTL. Async is fine.

Step Functions Lambda tasks read/write this directly. You no longer need a “memory service” Lambda in front. ElastiCache is the memory service.

Pattern 3 — DLQ retry coordinator

This is the one I keep underbuilding. SQS dead-letter queues are great at catching failures, but the recovery story is usually a Lambda that drains the DLQ and reprocesses blindly. That works until you have correlated failures — same downstream API outage hits 1000 messages, you reprocess them all, they all fail again, you back off and retry, repeat.

A cache-coordinated retry layer fixes this:

DLQ message arrives
→ cache lookup: dlq:<failure-fingerprint> ← ElastiCache
- count > N in window → don't retry yet, set circuit-open flag
- count ≤ N → increment, retry, on success delete key
→ on circuit-open: skip retries until TTL expires

The fingerprint is whatever isolates the failure class — downstream service ID + error code, for example. The cache holds the rolling counter and the open-circuit flag. Sync durability matters here: if the counter resets on AZ failover, you lose your back-pressure and slam the recovering downstream the moment it comes back. This is a place where the new sync mode pays for itself.

Bonus: the same cache can hold the per-key idempotency token so a retry that did partially succeed doesn’t double-charge a payment or double-write a record.

Choosing between sync, async, and DynamoDB

A rough heuristic I’m landing on:

Need	Pick
Rebuildable, hot path, cost matters	ElastiCache async
Correctness-critical, low write rate, microsecond reads	ElastiCache sync
Audit trail, queries beyond key lookup, infrequent access	DynamoDB
Big blob, write-once-read-many	S3, with ElastiCache pointer

DynamoDB doesn’t go away. It’s still the right answer for anything you’ll query by attribute, paginate, or audit. ElastiCache durability isn’t a DynamoDB replacement — it’s a way to stop using DynamoDB as a poor cache.

What I’m doing next

Adding a semantic-cache layer in front of the RAG step in our internal agent. Async writes, embedding-hash key, content-version included.
Replacing a small DynamoDB “agent scratchpad” table with a Valkey cluster for one workflow as a proof-of-concept. Sync writes for the slot the next state reads.
Sketching the DLQ coordinator pattern for our most retry-loud Step Function. This one I want to write a small spec for before building.

If the last time you touched a cache was Redis in some workflow tool, this announcement is a reason to revisit. The “cache vs database” line just moved.

Why MCP Clients on AgentCore Gateway Need OAuth Auth Code Flow (Not M2M)

Yoonsoo Park — Wed, 03 Jun 2026 11:45:00 -0400

AWS published a walkthrough for wiring OAuth 2.0 authorization code flow between an MCP client (Cursor, Claude Desktop, your own) and a Bedrock AgentCore Gateway acting as a tool server. It’s a good tutorial. What it doesn’t spell out — and what bit me when I started thinking about exposing internal tools to outside MCP clients — is the underlying decision: when do you actually need three-legged OAuth here, and what breaks if you cheap out with client credentials?

This post is the decision tree, not the tutorial.

The setup, briefly

AgentCore Gateway sits between an MCP client and your Lambda-backed tools:

MCP Client (Cursor / Claude Desktop / custom)
│ (MCP over HTTP+SSE, with bearer token)
▼
AgentCore Gateway ──► Cognito / Okta / Auth0 (token verification)
│
▼ (signed invoke)
Lambda Tools ──► DynamoDB / Salesforce / Jira / whatever

Gateway is the OAuth resource server. The IdP issues tokens. The MCP client presents them. Two flavors of token are possible:

Client credentials (M2M) — the MCP client itself authenticates as a service account. One token, no user identity, no per-user scoping.
Authorization code + PKCE — a real human signs in once via a browser redirect, the MCP client stores the resulting access + refresh token and presents the access token on every tool call.

AWS’s blog walks through option 2. The interesting question is why you’d bother.

When client credentials is enough

Be honest first. You don’t need auth code flow if all of these are true:

The tools operate on shared, non-user-scoped data (a public knowledge base, an internal metrics aggregator, a read-only catalog).
All callers are trusted (an internal agent platform, not a marketplace of third-party MCP clients).
Audit trails don’t need to attribute calls to a specific human.

In that world, one client_id + client_secret per MCP client is fine. Rotate the secret, scope the tools, ship it.

When you actually need auth code flow

The moment any of these show up, M2M falls apart:

Trigger	Why M2M breaks
Tools query per-user data (this user’s Salesforce records, this user’s Jira tickets, this user’s S3 prefix)	A shared service account either sees everything (over-privileged) or nothing (under-privileged). No middle ground without re-implementing auth inside the tool.
Multi-tenant SaaS integration	The tool needs to call a downstream API as the user. You’d otherwise have to store and impersonate per-user credentials in the tool — exactly the thing OAuth was invented to avoid.
Audit/compliance requires “who invoked this tool”	The token’s `sub` claim is your audit trail. M2M tokens have a service `sub`, not a human one.
Consent screens are a product requirement	Only auth code flow shows the user “this MCP client wants to read your X” before tokens are minted.

If you’re building a tool gateway for an internal agent that does platform work, M2M is fine. If you’re letting a user point Cursor at your gateway and have it act on their behalf, you need auth code flow. There is no middle option that doesn’t eventually become a homebrew auth system.

The three things that surprised me

The tutorial covers the happy path. These don’t get enough airtime.

1. MCP transports and browser redirects don’t naturally mix

OAuth auth code flow assumes a browser. MCP clients commonly run over stdio (Cursor, Claude Desktop) or SSE. Stdio has no browser. SSE has a browser but the MCP server doesn’t drive it.

The MCP spec’s answer is: the client opens a browser to the authorization endpoint when it doesn’t have a valid token, captures the redirect, exchanges the code, and stores the result. The gateway never touches a browser. This works, but means:

Every MCP client implements its own token cache and refresh logic. Cursor does it differently from Claude Desktop. Your custom client will too.
A redirect_uri of http://localhost:<random-port> is the only realistic option for desktop clients. Register a wildcard or a generous range with your IdP, or expect to whitelist new ports forever.

2. Registration is provider-specific, not automatic

RFC 7591 lets an MCP client self-register with the IdP at connection time. The final 2026-07-28 MCP specification formally deprecates Dynamic Client Registration in favor of Client ID Metadata Documents (CIMD), but that does not make every provider or AgentCore configuration dynamic. In the AWS Cognito walkthrough, you still pre-register the OAuth client; other identity providers and deployment paths may support different registration options.

Practical consequence: verify the registration method supported by the exact IdP and AgentCore path. For Cognito, pre-create the client and configure its redirect URIs and scopes; do not promise universal dynamic registration to MCP users.

3. Token lifetime ≠ agent session lifetime

A long-running agent session might span hours. Default access tokens are 60 minutes. Auth code flow gives you a refresh token, but:

Refresh in stdio MCP is non-trivial — the client has to detect a 401 from the gateway, run the refresh, retry. Most stock MCP client libraries don’t do this for you yet.
Refresh tokens are bearer secrets. Store them in OS keychain (Keychain on macOS, Credential Manager on Windows), not a JSON file in ~/.config/. Cursor and Claude Desktop do this; your custom client should too.
Idle expiration vs absolute expiration: pick a refresh token policy that survives a 4-hour agent run but doesn’t live forever. 30-day absolute, 24-hour idle is a reasonable starting point.

Scope design — the part everyone underestimates

Two ways to design scopes:

Per-tool scopes: tool:read-account, tool:create-opportunity, tool:run-report. Fine-grained, audit-friendly, but the consent screen turns into a wall of checkboxes and you’ll regret naming the 47th scope.

Domain scopes: crm:read, crm:write, analytics:read. Coarser, the consent screen is human-readable, but a single scope grants a basket of tools. Lateral movement risk if any one tool is compromised.

The right answer is usually domain scopes for the consent UX, plus tool-level authorization inside the gateway (the access token unlocks the door, the gateway’s policy decides which Lambda you can actually invoke). That way users see five checkboxes, not fifty, and you still get fine-grained control.

Pitfalls I’ve seen / expect to see

Mixing M2M and user clients in one Cognito resource server. Works, but the scopes pollute each other and the consent screen shows M2M-only scopes to humans. Use two resource servers from day one.
Forgetting redirect_uri for http://localhost in non-prod. Cognito, Okta, and Auth0 all let you register it; if you don’t, local dev breaks and the error message points at the wrong layer.
Trusting the IdP’s aud claim default. AgentCore Gateway expects a specific audience. Cognito’s default for user-pool tokens is the user pool’s app client ID, which is not what Gateway wants if you’ve set up an explicit resource server. Configure the audience explicitly on both sides.
Skipping PKCE because “we’re using a confidential client”. Auth code flow without PKCE on a public client (every desktop MCP client is public) is a downgrade attack waiting to happen. PKCE is free; turn it on.
Logging access tokens in CloudWatch. Gateway request logs at debug level can include the Authorization header. Strip it before shipping logs anywhere durable.

A decision tree, in one paragraph

If your tool reads or writes user-scoped data, or you’ll ever need to know which human invoked a call, use auth code flow with PKCE. Choose the IdP based on its current AgentCore integration and registration support, not a generic provider checklist. Design domain-level scopes for the consent screen, enforce tool-level policy inside Gateway, and pre-register clients where the provider requires it. Store refresh tokens in OS keychain. Set token lifetimes to match agent session expectations, not IdP defaults. Don’t put both M2M and user clients in the same resource server. Test the local dev redirect path before you test the prod one.

The AWS tutorial is the right thing to follow once you’ve decided. The deciding is the part you have to do yourself.

Per-Request Cost Attribution on Amazon Bedrock — InvokeModel Metadata, Inference Profiles, and What to Use When

Yoonsoo Park — Mon, 01 Jun 2026 02:30:00 -0400

If you run more than one team, product, or environment on top of Amazon Bedrock, the very first finance question you’ll hear is: “who used the tokens?” And until recently, the honest answer was “it depends on which API you’re calling.”

The Converse and ConverseStream APIs already supported a requestMetadata field — arbitrary key/value tags that flow into your invocation logs. But a lot of production code still uses the older, lower-level InvokeModel and InvokeModelWithResponseStream APIs, and those didn’t accept metadata at all. You either had to migrate to Converse, separate workloads behind different inference profiles, or live with IAM-role-level granularity.

In May 2026, AWS closed that gap: InvokeModel and InvokeModelWithResponseStream now accept request-level metadata too, available in every commercial region where Bedrock is offered.

That sounds small. It isn’t. It changes which attribution strategy is the right default.

Three ways to attribute Bedrock spend

There are now three production-grade ways to slice “who used what” on Bedrock. They aren’t mutually exclusive — most mature setups use two of them at once — but they answer different questions.

Mechanism	Granularity	What it answers
Application Inference Profile	Per service / per app	“How much does this product cost to run?”
IAM principal (role/user)	Per role	“How much did this caller spend?”
Request metadata (new)	Per request	“How much did this team / project / env / user spend, even on a shared profile?”

Application inference profiles

If you’ve already built a platform team, this is probably your current default. You provision an inference profile per service, route the service’s traffic through it, and Cost Explorer breaks the bill down by profile ARN. Clean, audit-friendly, and works for any Bedrock model that supports application inference profiles (notably the Claude family via cross-region inference).

The catch: profiles are a coarse unit. If three internal teams share one “shared experimentation” service, they all show up under the same profile.

IAM-based attribution

Free, automatic, and the lowest-effort tier. Cost Explorer can group spend by IAM principal if your callers each have distinct roles. Works the moment you turn it on, and pairs well with SSO. The downside is that it’s only as granular as your IAM design — and most teams converge on a small number of “service roles” that hide a lot of internal structure.

Request metadata

This is the new one. You attach a small map of tags — say { "team": "growth", "project": "onboarding-assistant", "env": "prod", "actor_group": "beta" } — to each InvokeModel call. The tags land in your model invocation log on S3 (or CloudWatch), and you query them with Athena, OpenSearch, or whatever you already use.

The win is post-hoc flexibility. You don’t have to redesign your IAM tree or split inference profiles to ask a new question. Tag every call with team and feature, and you can re-slice spend by either dimension forever after.

When each one wins

Here’s the rule of thumb I’ve landed on after running this in production:

Inference profiles are the right unit for billing chargeback between teams that own separate products. They show up cleanly in AWS Cost Explorer, the bill is hard to game, and they give the platform team a real handle (rate limits, model access, regional routing).
IAM is the right unit for security boundaries. If two roles can see each other’s data, no amount of metadata tagging fixes that. Use IAM to enforce isolation; don’t use it as your primary cost knob.
Request metadata is the right unit for product analytics and per-feature unit economics. “How much does the suggestion box cost per active user?” “Did the new prompt template raise our per-conversation token cost?” These are questions you’ll keep inventing, and you don’t want to file an infra ticket every time.

In a healthy setup all three coexist: profiles for the bill, IAM for the blast radius, metadata for the dashboard.

Wiring it up

The mechanics are simple, but there are three steps you can’t skip.

1. Turn on model invocation logging

Metadata only matters if you can read it back. Enable Bedrock model invocation logging in each region you call from, and pick a destination — S3 for cheap long-term storage and Athena queries, CloudWatch Logs if you want to grep in real time. Both is fine; you’ll usually settle on one.

This is a per-region setting and it’s easy to forget when you spin up a new region. Put it in your account-bootstrap CDK / Terraform.

2. Pass `requestMetadata` on every call

For InvokeModel and InvokeModelWithResponseStream, the new requestMetadata parameter takes a flat string-to-string map. Keys and values are limited in length (think tag-style budgets, not blob storage), and the same field works on Converse / ConverseStream for code paths that already use those.

The critical move is to inject metadata in your shared client wrapper, not in each call site. If you let individual features set their own tags, you’ll end up with a soup of inconsistent keys (team, Team, team_name, owning_team) and your dashboards will lie. Pick a schema, write it down, enforce it in one place.

A reasonable starter schema:

Key	Example	Required?
`team`	`growth`, `core`, `platform`	yes
`service`	`onboarding-assistant`	yes
`env`	`dev`, `qa`, `prod`	yes
`feature`	`summarize`, `chat`, `eval`	optional
`request_id`	`req_01J…` (your own correlation id)	optional

Resist the urge to put PII or full user IDs in there unless you’ve thought through retention. Logs live for a long time.

3. Query the logs

If you’re on S3, the official partition layout plays well with Athena. A first query usually looks like:

1
2
3
4
5
6
7
8
9


SELECT
 request_metadata['team'] AS team,
 request_metadata['service'] AS service,
 SUM(input_token_count) AS input_tokens,
 SUM(output_token_count) AS output_tokens
FROM bedrock_invocation_logs
WHERE date = current_date - interval '7' day
GROUP BY 1, 2
ORDER BY input_tokens + output_tokens DESC

Translate tokens to an estimate with the published per-model rates and you have a per-team dashboard, sliceable by any tag you set. Request metadata is log context, not a Cost Explorer/CUR cost-allocation tag; use application inference profiles or the supported AWS cost-management features when you need invoice-grade billed dollars.

Pitfalls I’ve actually hit

A few things to save you a debug session:

Region mismatches. Logging is per-region. Calls to a model in a region where logging is off are absent from your metadata dashboard even though the underlying Bedrock spend still exists in AWS billing.
Streaming responses. InvokeModelWithResponseStream records token counts only after the stream completes. If your client disconnects early, the row may still be written but with partial data. Don’t assume every row is “clean.”
Schema drift. Once you ship a metadata schema, treat it like a public API. Renaming team to owning_team six months in will fork your dashboards. Add new keys, deprecate old ones, never silently rename.
Don’t tag what IAM should enforce. If env=prod is a metadata tag, anyone with InvokeModel permission can claim to be prod. Use IAM (and ideally separate roles per env) for anything that must not be forgeable.

So which one should you use?

If you’re starting today on Bedrock:

Set up at least one inference profile per product that has its own bill or SLO. This is your invoice-grade unit.
Give each calling service a distinct IAM role, even if it’s tedious. Future-you will thank present-you when the security review lands.
Add request metadata in your shared client wrapper from day one, with a small, enforced schema. It costs nothing extra at runtime and gives you a permanent escape hatch for the questions you haven’t thought of yet.

The new InvokeModel metadata feature isn’t going to change your architecture. But it does mean you no longer have to choose between “use the modern Converse API” and “have per-request attribution.” You can keep your existing InvokeModel-based code and still get the granularity that used to require a migration — which, in practice, is how most of these features actually get adopted.

References

Docker Build SSL Failures Behind a Corporate MITM Proxy: Two Patterns

Yoonsoo Park — Sat, 30 May 2026 12:30:00 -0400

If you work somewhere with Zscaler or Netskope, Cisco Umbrella, … any “secure web gateway” that does TLS interception; you have probably seen this during a docker build:

ERROR: Could not install packages due to an OSError:
HTTPSConnectionPool(host='files.pythonhosted.org', port=443):
Max retries exceeded with url: .../something-1.9.0-py3-none-any.whl.metadata
(Caused by SSLError(SSLCertVerificationError(1,
'[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed:
unable to get local issuer certificate (_ssl.c:1032)')))

Your host laptop is fine — macOS Keychain trusts the proxy’s root CA. The Docker container is not, because it’s a fresh Linux filesystem with only the public CA bundle. The proxy intercepts the TLS handshake to PyPI, presents its own cert, and the container has no idea who signed it.

The fix is the same idea in both directions: get the proxy’s root CA into the container’s trust store before the package manager runs. The how-to differs depending on whether you control the Dockerfile or not.

Pattern 1 — You control the Dockerfile (custom images, `DockerImageAsset`)

This is the easy case. Add an early RUN block that takes a base64-encoded cert as a build arg and installs it.

1
2
3
4
5


ARG ZSCALER_CERT_BASE64
RUN if [ -n "$ZSCALER_CERT_BASE64" ]; then \
 echo "$ZSCALER_CERT_BASE64" | base64 -d > /usr/local/share/ca-certificates/zscaler.crt && \
 update-ca-certificates; \
 fi

Two things matter here:

Position: this block must come before any pip install, apt-get update (over HTTPS), npm install, etc. Anything that hits the internet needs the trust store updated first.
It’s gated on the build arg. When the build arg is empty (CI/CD, where there is no proxy), the block is a no-op. You don’t want to ship a Zscaler cert to production.

On the build orchestrator side (CDK in my case), pull the cert from Keychain at synth time:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


import { execSync } from 'child_process';

function getZscalerCertBase64(): string {
 const pem = execSync(
 'security find-certificate -a -c "Zscaler" -p /Library/Keychains/System.keychain',
 { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }
 );
 if (!pem || pem.trim().length === 0) {
 throw new Error('No Zscaler cert in System Keychain');
 }
 return Buffer.from(pem).toString('base64');
}

const buildArgs: Record<string, string> = {};
if (devMode) {
 buildArgs.ZSCALER_CERT_BASE64 = getZscalerCertBase64();
}

new DockerImageAsset(this, 'ImageAsset', { directory: srcDir, buildArgs });

security find-certificate -a -c "Zscaler" -p returns one or more PEM blocks concatenated. Base64-encode the whole blob; on the container side, update-ca-certificates happily handles a multi-cert PEM bundle.

That’s it for images you own.

Pattern 2 — You don’t control the Dockerfile (`PythonFunction`, `PythonLayerVersion`)

This is the case that took me a few hours to figure out. AWS CDK’s @aws-cdk/aws-lambda-python-alpha (PythonFunction, PythonLayerVersion) bundles your Lambda code by spinning up public.ecr.aws/sam/build-python3.13 (or whichever runtime) and running pip install inside that container. You don’t write that Dockerfile. So Pattern 1 doesn’t help.

The fix: pre-bake a custom bundling image with the Zscaler cert already installed, push it to ECR, and tell CDK to use that image instead of the default SAM one.

The custom bundling Dockerfile

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30


ARG IMAGE=public.ecr.aws/sam/build-python3.13
FROM $IMAGE

ARG ZSCALER_CERT_BASE64=""

ENV PIP_CACHE_DIR=/tmp/pip-cache
ENV POETRY_CACHE_DIR=/tmp/poetry-cache
ENV UV_CACHE_DIR=/tmp/uv-cache
ENV PATH="/usr/app/venv/bin:$PATH"

USER root

RUN if [ -n "$ZSCALER_CERT_BASE64" ]; then \
 echo "$ZSCALER_CERT_BASE64" | base64 -d > /etc/pki/ca-trust/source/anchors/zscaler.crt && \
 update-ca-trust extract; \
 fi

ENV REQUESTS_CA_BUNDLE=/etc/pki/tls/certs/ca-bundle.crt
ENV SSL_CERT_FILE=/etc/pki/tls/certs/ca-bundle.crt
ENV UV_NATIVE_TLS=true

RUN python -m venv /usr/app/venv && \
 mkdir -p /tmp/pip-cache /tmp/poetry-cache /tmp/uv-cache && \
 chmod -R 777 /tmp/pip-cache /tmp/poetry-cache /tmp/uv-cache && \
 pip install --upgrade pip && \
 pip install pipenv poetry uv && \
 rm -rf /tmp/pip-cache/* /tmp/poetry-cache/* /tmp/uv-cache/*

USER nobody
CMD [ "python" ]

Build it once, push to ECR:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


aws ecr create-repository --repository-name python-bundling --region us-east-1 || true

ZSCALER_CERT_BASE64=$(security find-certificate -a -c "Zscaler" -p /Library/Keychains/System.keychain | base64)

docker build \
 --build-arg ZSCALER_CERT_BASE64="$ZSCALER_CERT_BASE64" \
 -t "$ACCOUNT.dkr.ecr.us-east-1.amazonaws.com/python-bundling:3.13" \
 scripts/build/python-bundling

aws ecr get-login-password --region us-east-1 | \
 docker login --username AWS --password-stdin "$ACCOUNT.dkr.ecr.us-east-1.amazonaws.com"

docker push "$ACCOUNT.dkr.ecr.us-east-1.amazonaws.com/python-bundling:3.13"

Then in CDK, swap the bundling image only in dev mode:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22


import { DockerImage } from 'aws-cdk-lib';

function getBundlingImage(account: string, region: string, devMode: boolean) {
 if (!devMode) return undefined; // CI/CD uses the default SAM image
 return DockerImage.fromRegistry(
 `${account}.dkr.ecr.${region}.amazonaws.com/python-bundling:3.13`
 );
}

const image = getBundlingImage(account, region, devMode);

new PythonLayerVersion(this, 'Layer', {
 entry: path.join(__dirname, '..', 'layers', 'shared'),
 compatibleRuntimes: [Runtime.PYTHON_3_13],
 ...(image && { bundling: { image } }),
});

new PythonFunction(this, 'Fn', {
 entry: path.join(__dirname, '..', 'functions', 'create_chat'),
 runtime: Runtime.PYTHON_3_13,
 ...(image && { bundling: { image } }),
});

Once the image is in ECR, every project in that account can reuse it. No more rebuilding per project.

Pitfalls I actually hit

Wrong cert path for the base distro. SAM build images are Amazon Linux. The trust store path is /etc/pki/ca-trust/source/anchors/ and the update command is update-ca-trust extract. If you copy a Debian/Ubuntu snippet (/usr/local/share/ca-certificates/ + update-ca-certificates), the cert is silently ignored and you keep getting the same SSL error wondering why your “fix” didn’t take.
chmod 755 on pip cache dirs. CDK runs the bundling container as a non-root user (typically 503:20). With chmod 755 on /tmp/pip-cache, the rsync step at the end of bundling fails with exit code 23 because the non-root user can’t write. chmod 777 on cache dirs is annoying but necessary inside throwaway bundling images.
uv ignoring the system trust store. uv ships its own TLS implementation by default. Setting UV_NATIVE_TLS=true makes it fall back to OpenSSL’s CA store, which is where update-ca-trust puts your cert. Without this env var, your cert is in the right place and uv still doesn’t see it.
CI/CD doesn’t have the proxy. Both patterns are gated on devMode. CodePipeline, GitHub Actions runners, etc. talk to PyPI directly; injecting a stale Zscaler cert there is at best wasted bytes and at worst a footgun if the cert ever expires. Always make the injection conditional.
security find-certificate is macOS-only. Linux dev hosts behind the same proxy need a different extraction (/etc/ssl/certs/... or whatever your IT pushes). The CDK code should detect host OS and either extract differently or skip injection entirely.
Multiple Zscaler certs in Keychain. security find-certificate -a -c "Zscaler" -p concatenates every match. That’s fine — update-ca-trust and update-ca-certificates both accept multi-cert PEM bundles. Don’t try to filter to “just one”.

What to do

If you’re hitting this for the first time and it’s a custom image you wrote, use Pattern 1 — five lines of Dockerfile and a build arg. If it’s PythonFunction/PythonLayerVersion (or any CDK construct that picks its own bundling image), bite the bullet, build the custom bundling image once, push to ECR, and gate it behind a devMode check.

The 10 minutes you spend setting up Pattern 2 saves you from the next three hours of “but I added the cert, why is pip still failing?” — because pip is running in a container you didn’t write, and you can’t add the cert without owning that container.

Bruno + AWS SigV4 with an SSO Profile (No More Pasting Access Keys)

Yoonsoo Park — Thu, 28 May 2026 11:50:00 -0400

If you’ve been hitting an IAM-protected API Gateway with Bruno (or Postman, or Insomnia) the old way, you know the dance: aws configure export-credentials, copy three values, paste them into the auth panel, hit send, hit send again two hours later, swear, repeat. Everyone who works with SSO ends up with a TODO buried somewhere that says “automate this.”

Turns out you don’t have to. Bruno’s AWS SigV4 auth has a profileName field that reads directly from ~/.aws/config and ~/.aws/sso/cache/. Set it once, log in to SSO once a day, and Bruno does the rest.

The setup

Two files. opencollection.yml at the collection root for the auth config, and an environment file per AWS account/profile.

Collection-level auth — `opencollection.yml`

1
2
3
4
5
6
7
8
9


request:
 auth:
 type: awsv4
 accessKeyId: ""
 secretAccessKey: ""
 sessionToken: ""
 service: execute-api
 region: "{{aws_region}}"
 profileName: "{{aws_profile}}"

The three credential fields stay empty strings. When Bruno sees a non-empty profileName, it ignores them and resolves credentials through the AWS SDK’s profile chain — which means SSO sessions, role assumptions, and credential_process all just work.

service: execute-api is for API Gateway. Swap it for lambda, s3, bedrock, whatever you’re hitting. region and profileName come from the environment.

Environment files — `environments/dev.yml`

1
2
3
4
5
6
7
8


name: Dev
variables:
 - name: aws_profile
 value: gap-dev
 - name: aws_region
 value: us-east-1
 - name: api_base_url
 value: https://abc123.execute-api.us-east-1.amazonaws.com/blue

One file per environment. Switching account is now a click in Bruno’s environment dropdown — no auth panel to touch.

1

aws sso login --profile gap-dev

That’s the only ritual. SSO tokens last 8–12 hours depending on your org’s config; once a day in the morning, done.

Why this is worth the five minutes

A few things you stop doing:

Pasting credentials into a collection file. Even with gitignore, temp creds end up in chat, in a screenshot, in a .env.local you forgot about.
Re-exporting every two hours. SSO temp creds are short-lived. With a static paste, you’re refreshing constantly. With profileName, the SDK refreshes for you.
Mixing up environments. The auth block is the same across dev/qa/prod — only the environment variable changes. There’s no profile-specific access key sitting in the wrong panel.

Pitfalls I’ve actually hit

SSO token expired. Bruno will sign with a stale session and you’ll get a confusing 403. aws sso login --profile <name> and retry. If you hit a lot of these, alias aws sso login --profile <name> to something short.
Wrong profile name. Bruno fails silently to “no credentials found” if profileName doesn’t match anything in ~/.aws/config. Run aws configure list-profiles to confirm the exact string.
Mixing auth modes. If you accidentally leave a real access key in accessKeyId, Bruno may use it instead of the profile depending on version. Keep those fields strict empty strings.
credential_process profiles work too. If your org uses credential_process (corporate SSO wrapper, Granted, etc.), Bruno picks it up — same profileName field, no extra config.
Region mismatch. SigV4 signatures include the region. If your env file says us-east-1 but you’re calling a us-west-2 endpoint, the signature is invalid. Easy to miss when you copy a URL across environments.
Collection-level vs request-level auth. If a single request overrides auth to something else, your collection-level SigV4 doesn’t apply. Check auth: { type: inherit } or remove the override.

SigV4 fields Bruno supports

For reference, when you open the AWS Sig auth panel in the UI:

Access Key ID
Secret Access Key
Session Token
Service (e.g. execute-api, s3, lambda, bedrock)
Region (e.g. us-east-1)
Profile Name — the one that makes the other three obsolete

If profileName is set, the first three are ignored. That’s the whole trick.

The short version

Empty strings in the credential fields, profileName: "{{aws_profile}}", one env var per environment, aws sso login in the morning. Stop pasting temp creds into your API client.

Adding llms.txt to a Hugo Blog with Output Formats

Yoonsoo Park — Wed, 27 May 2026 03:00:00 -0400

In September 2024, Jeremy Howard (Answer.AI / fast.ai) proposed /llms.txt — a curated, plain-Markdown index that sits at a site’s root, alongside robots.txt and sitemap.xml. The pitch: LLM context windows are tiny, HTML is noisy, and crawlers shouldn’t have to parse 180 HTML pages to understand what your site is about. So give them a hand-curated map.

Sounds reasonable. The harder question is whether it does anything yet.

What `llms.txt` actually is

It’s a Markdown file with a strict, parseable structure:

# Site Name ← H1, exactly one, required
> One-line summary ← blockquote
Free-form prose (optional)
## Docs ← H2 sections
- [Title](URL): short description
## Optional ← reserved meaning: skip if context is tight
- [Appendix](URL)

Two adjacent conventions show up in the spec:

llms-full.txt — same idea, but with all the linked content inlined into a single file. Useful for “drop the entire docs into a context window.”
.md mirror URLs — every page at /foo/ is also reachable at /foo.md as clean Markdown. nbdev does this automatically; FastHTML pioneered the pattern.

Adoption: docs sites yes, LLM providers… not really

Documentation sites have adopted it widely. Anthropic’s docs, Cloudflare, Mintlify (auto-generated), Vercel, Supabase, Hugging Face, FastHTML — all publish /llms.txt. Mintlify, Fern, and Docusaurus plugins are doing most of the heavy lifting in spreading it.

The part nobody likes to say out loud: none of the major LLM providers have publicly committed to fetching it. OpenAI’s GPTBot, Anthropic’s ClaudeBot, Google-Extended — they all crawl HTML and follow sitemap.xml. None of their published docs say llms.txt is preferred or even read. John Mueller (Google) commented in late 2024 that there was no evidence any AI service was using it.

So today, llms.txt is closer to good documentation hygiene than a working SEO channel. The cost of adding one is near-zero, though, and if/when providers start consuming it, you’re already there.

Implementation in Hugo

Two ways to add it:

Drop a static static/llms.txt file. Done. Stale within a month.
Generate it from your content via Hugo’s Output Formats so it stays current with every post.

(2) is the only correct answer for a blog where posts are added regularly.

Step 1 — register the output format

In config.yaml:

1
2
3
4
5
6
7
8
9


outputFormats:
 LLMS:
 mediaType: "text/plain"
 baseName: "llms"
 isPlainText: true
 notAlternative: true

outputs:
 home: ["HTML", "RSS", "JSON", "LLMS"]

isPlainText: true skips Hugo’s HTML-aware processing. notAlternative: true keeps it out of the <link rel="alternate"> chain — llms.txt is not an alternate representation of the homepage.

Step 2 — write the template

layouts/index.llms.txt:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


# {{ .Site.Title }}

> {{ .Site.Params.siteDesc }}

{{ .Site.Params.siteName }} is the personal tech blog of {{ .Site.Params.author }}.

## Pages
- [About]({{ "about.html" | absURL }}): About the author
- [Articles]({{ "articles.html" | absURL }}): Curated articles index

## Blog Posts
{{- range first 80 (where .Site.RegularPages "Section" "blog") }}
- [{{ .Title }}]({{ .Permalink }}){{ with (.Description | default (.Summary | plainify | truncate 140)) }}: {{ . }}{{ end }}
{{- end }}

## Optional
- [RSS Feed]({{ "index.xml" | absURL }})
- [Tags]({{ "tags/" | absURL }})

Build, and Hugo emits public/llms.txt automatically. Sync to S3 / CloudFront like any other static file. Verify the Content-Type:

1
2
3


hugo --gc --minify
head public/llms.txt # starts with '# thats.nono'
curl -I https://www.yopa.page/llms.txt # Content-Type: text/plain

That’s it.

What I didn’t add (yet)

llms-full.txt. Tempting, but for a blog with 180+ posts it’d be massive, and there’s no evidence anyone is fetching it.
.md mirror URLs. Two extra lines in outputs.page would do it, but it doubles the surface area for caching headaches and content drift. Defer.

Honest take

I added llms.txt to yopa.page because the cost is one template and zero ongoing maintenance, not because I expect Claude or ChatGPT to start reading it tomorrow. If the standard catches on, my site is ready. If it doesn’t, I lost 30 minutes but well?

That asymmetry — cheap to adopt, free option on future upside — is the whole reason to do this now. Don’t rewrite your content strategy around it. Don’t tell your boss it’ll move SEO numbers. Just ship the file and move on.

References

Spec: https://llmstxt.org/
Repo: https://github.com/AnswerDotAI/llms-txt
This blog’s llms.txt
PR that added it: ypark9/yopa.page#19

Deploy Your Own AI Agent to AWS — Hermes on ECS Fargate with Slack Integration

Yoonsoo Park — Sat, 23 May 2026 00:00:00 +0000

A May 2026 field guide to running your own AI agent on AWS. The infrastructure and gotchas are real, but the upstream image and configuration must be re-checked before a new deployment.

Hermes Agent (NousResearch) | Hermes Docker deployment | AWS CDK Documentation | Slack Socket Mode

Review note (2026-08-28): This article records a deployment from May 23, 2026. Hermes now documents a supported Docker path using the nousresearch/hermes-agent image and persistent data mounted at /opt/data; schema migrations can create backups. The ECS/CDK architecture below is illustrative for this snapshot. Inspect the current release page and configuration reference before copying it, and never overwrite a mounted config or secret store blindly.

Most AI agent tutorials end at “run it locally.” That’s fine for demos, but useless for teams. You want an always-on assistant that your team can DM on Slack, that remembers past conversations, that can read your documentation and use external tools — and that doesn’t die when your laptop goes to sleep.

This post documents how I deployed Hermes Agent — an open-source AI agent framework by NousResearch — to AWS ECS Fargate, connected it to Slack via Socket Mode, backed it with Claude on Bedrock, and gave it persistent memory on EFS with a knowledge base on S3. The code blocks are copy-paste-able for that May snapshot only; validate image tags, configuration keys, and mount paths against the current upstream docs. Every gotcha is one I actually hit.

What You’ll Build

A single Hermes Agent running on ECS Fargate that:

Connects to your Slack workspace via Socket Mode (DMs and @mentions)
Uses Claude (Sonnet or Opus) via Amazon Bedrock for inference
Persists memory and learned skills on EFS across restarts
Syncs a knowledge base from S3 every 15 minutes (no redeploy needed for updates)
Supports MCP servers for external tool integration (Jira, GitHub, etc.)

Estimated monthly cost: ~$55–65 (excluding Bedrock inference, which varies by usage).

Prerequisites

AWS account with Bedrock model access enabled (Claude models in us-east-1)
AWS CLI v2 configured with credentials
Node.js 18+ and npm (for CDK)
Docker Desktop
A Slack workspace where you can install apps
Basic familiarity with CDK, Docker, and ECS concepts

Important: Enable Bedrock model access first. Go to AWS Console → Bedrock → Model access → Request access to Anthropic Claude models. This can take minutes to hours.

Architecture Overview

Why This Architecture?

Socket Mode eliminates 80% of networking complexity. Traditional Slack bots need an inbound HTTP endpoint — meaning a load balancer, public IP, TLS certificate, and DNS. Socket Mode flips this: the container initiates an outbound WebSocket to Slack. No ALB ($16/month saved), no public IP, no cert management. The container sits in a private subnet and is unreachable from the internet.

EFS persists agent state across deployments. Hermes stores conversation memory in SQLite, learned skills as files, and user profiles on disk. Without EFS, every deployment wipes this state. With EFS, the agent remembers everything even after a fresh container starts.

S3 decouples knowledge updates from container restarts. Upload new docs to S3, and the agent picks them up within 15 minutes. No Docker build, no ECR push, no deployment. This is the key insight that makes the system operationally pleasant.

Private subnet + NAT Gateway gives an outbound-only security posture. The container can reach Slack, Bedrock, and S3 — but nothing on the internet can reach the container.

Step 1: Create the Slack App

Before we touch AWS, let’s create the Slack app and collect our tokens.

1.1 Create the App

Go to api.slack.com/apps
Click “Create New App” → “From scratch”
Name it (e.g., “Hermes”), select your workspace

1.2 Enable Socket Mode

Go to Settings → Socket Mode
Toggle Enable Socket Mode to ON
When prompted, create an app-level token:
- Name it socket-mode
- Add the connections:write scope
Click Generate
Save this token — it starts with xapp- (this is your SLACK_APP_TOKEN)

1.3 Add Bot Token Scopes

Go to OAuth & Permissions → Scopes → Bot Token Scopes and add:

Scope	Why
`chat:write`	Send messages
`im:write`	Open DMs
`im:read`	Read DM conversations
`im:history`	Access DM message history
`app_mentions:read`	Respond to @mentions in channels
`channels:read`	List public channels

1.4 Enable the Messages Tab (DMs)

Go to App Home and check “Allow users to send Slash commands and messages from the messages tab”. Without this, users cannot DM your bot — the message input won’t appear.

Go to Event Subscriptions → Toggle ON → Under Subscribe to bot events, add:

message.im — Receive DM messages
app_mention — Respond to @mentions in channels

This step is critical. If you skip it, your bot’s Socket Mode connection will succeed (you’ll see logs), but no messages will ever arrive. The gateway runs, the container is healthy, yet the bot is deaf.

1.6 Install to Workspace

Go to OAuth & Permissions
Click “Install to Workspace”
Authorize the requested permissions
Save the Bot User OAuth Token — starts with xoxb- (this is your SLACK_BOT_TOKEN)

Any time you change scopes or event subscriptions, you must reinstall the app. Slack won’t apply changes until you do.

1.7 Test the App Exists

Open Slack, go to Apps, find your bot. Send it “hello” — it won’t respond yet (no backend), but you should see it in the app list.

Keep both tokens safe. We’ll store them in AWS Secrets Manager next.

Step 2: AWS Infrastructure with CDK

We’ll use CDK (TypeScript) to create all AWS resources. The complete stack creates: VPC networking, EFS, S3, Secrets Manager, ECS Cluster, Fargate Service, and all IAM permissions.

2.1 Project Setup

1
2
3


mkdir hermes-infra && cd hermes-infra
npx cdk init app --language typescript
npm install aws-cdk-lib constructs

2.2 The Stack

Replace lib/hermes-infra-stack.ts with:

 1
 2
 3
 4
 5
 6
 7
 8
 9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185


import * as cdk from 'aws-cdk-lib';
import * as ec2 from 'aws-cdk-lib/aws-ec2';
import * as ecs from 'aws-cdk-lib/aws-ecs';
import * as efs from 'aws-cdk-lib/aws-efs';
import * as iam from 'aws-cdk-lib/aws-iam';
import * as logs from 'aws-cdk-lib/aws-logs';
import * as s3 from 'aws-cdk-lib/aws-s3';
import * as secretsmanager from 'aws-cdk-lib/aws-secretsmanager';
import { Construct } from 'constructs';

export class HermesAgentStack extends cdk.Stack {
 constructor(scope: Construct, id: string, props?: cdk.StackProps) {
 super(scope, id, props);

 // --- Networking ---
 // Use an existing VPC or create a new one.
 // If creating new: this provisions public + private subnets with a NAT Gateway.
 const vpc = new ec2.Vpc(this, 'HermesVpc', {
 maxAzs: 2,
 natGateways: 1,
 });

 // Security group: outbound HTTPS only (Slack, Bedrock, S3)
 const taskSg = new ec2.SecurityGroup(this, 'TaskSg', {
 vpc,
 description: 'Hermes Agent - outbound HTTPS only',
 allowAllOutbound: false,
 });
 taskSg.addEgressRule(ec2.Peer.anyIpv4(), ec2.Port.tcp(443), 'HTTPS outbound');

 // --- Storage ---

 // EFS for persistent state (memories, skills, SQLite)
 const fileSystem = new efs.FileSystem(this, 'HermesState', {
 vpc,
 encrypted: true,
 lifecyclePolicy: efs.LifecyclePolicy.AFTER_30_DAYS,
 removalPolicy: cdk.RemovalPolicy.RETAIN,
 performanceMode: efs.PerformanceMode.GENERAL_PURPOSE,
 });

 const accessPoint = fileSystem.addAccessPoint('HermesAccess', {
 path: '/hermes',
 createAcl: { ownerUid: '1000', ownerGid: '1000', permissions: '750' },
 posixUser: { uid: '1000', gid: '1000' },
 });

 // Allow Fargate task to reach EFS (NFS port 2049)
 fileSystem.connections.allowDefaultPortFrom(taskSg);

 // S3 bucket for knowledge base
 const knowledgeBucket = new s3.Bucket(this, 'KnowledgeBucket', {
 bucketName: `hermes-knowledge-${this.account}`,
 encryption: s3.BucketEncryption.S3_MANAGED,
 removalPolicy: cdk.RemovalPolicy.RETAIN,
 });

 // --- Secrets ---

 const slackBotToken = new secretsmanager.Secret(this, 'SlackBotToken', {
 secretName: 'hermes/slack-bot-token',
 description: 'Slack Bot OAuth Token (xoxb-...)',
 });

 const slackAppToken = new secretsmanager.Secret(this, 'SlackAppToken', {
 secretName: 'hermes/slack-app-token',
 description: 'Slack App-Level Token for Socket Mode (xapp-...)',
 });

 // --- ECS ---

 const cluster = new ecs.Cluster(this, 'Cluster', {
 vpc,
 clusterName: 'hermes-agent',
 });

 const taskDef = new ecs.FargateTaskDefinition(this, 'TaskDef', {
 cpu: 512,
 memoryLimitMiB: 1024,
 runtimePlatform: {
 cpuArchitecture: ecs.CpuArchitecture.X86_64,
 operatingSystemFamily: ecs.OperatingSystemFamily.LINUX,
 },
 });

 // --- IAM Permissions ---

 // Bedrock: invoke Claude models (wildcard region for cross-region inference)
 taskDef.taskRole.addToPrincipalPolicy(new iam.PolicyStatement({
 actions: [
 'bedrock:InvokeModel',
 'bedrock:InvokeModelWithResponseStream',
 'bedrock:ListFoundationModels',
 'bedrock:ListInferenceProfiles',
 ],
 resources: [
 'arn:aws:bedrock:*::foundation-model/anthropic.*',
 `arn:aws:bedrock:*:${this.account}:inference-profile/*`,
 `arn:aws:bedrock:*:${this.account}:application-inference-profile/*`,
 ],
 }));

 // S3: read knowledge bucket
 knowledgeBucket.grantRead(taskDef.taskRole);

 // EFS: mount and write
 taskDef.taskRole.addToPrincipalPolicy(new iam.PolicyStatement({
 actions: ['elasticfilesystem:ClientMount', 'elasticfilesystem:ClientWrite'],
 resources: [fileSystem.fileSystemArn],
 }));

 // --- EFS Volume ---

 taskDef.addVolume({
 name: 'hermes-state',
 efsVolumeConfiguration: {
 fileSystemId: fileSystem.fileSystemId,
 transitEncryption: 'ENABLED',
 authorizationConfig: {
 accessPointId: accessPoint.accessPointId,
 iam: 'ENABLED',
 },
 },
 });

 // --- Container ---

 const logGroup = new logs.LogGroup(this, 'Logs', {
 logGroupName: '/ecs/hermes-agent',
 retention: logs.RetentionDays.TWO_WEEKS,
 removalPolicy: cdk.RemovalPolicy.DESTROY,
 });

 const container = taskDef.addContainer('hermes', {
 image: ecs.ContainerImage.fromEcrRepository(
 cdk.aws_ecr.Repository.fromRepositoryName(this, 'Repo', 'hermes-agent'),
 ),
 environment: {
 HERMES_HOME: '/data/hermes',
 AWS_DEFAULT_REGION: 'us-east-1',
 KNOWLEDGE_BUCKET: knowledgeBucket.bucketName,
 },
 secrets: {
 SLACK_BOT_TOKEN: ecs.Secret.fromSecretsManager(slackBotToken),
 SLACK_APP_TOKEN: ecs.Secret.fromSecretsManager(slackAppToken),
 },
 logging: ecs.LogDrivers.awsLogs({
 streamPrefix: 'hermes',
 logGroup,
 }),
 healthCheck: {
 command: ['CMD-SHELL', 'true'],
 interval: cdk.Duration.seconds(60),
 timeout: cdk.Duration.seconds(5),
 retries: 3,
 },
 });

 container.addMountPoints({
 sourceVolume: 'hermes-state',
 containerPath: '/data/hermes',
 readOnly: false,
 });

 // --- Fargate Service ---

 new ecs.FargateService(this, 'GatewayService', {
 cluster,
 taskDefinition: taskDef,
 desiredCount: 1,
 securityGroups: [taskSg],
 vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS },
 serviceName: 'hermes-gateway',
 enableExecuteCommand: true,
 circuitBreaker: { enable: true, rollback: true },
 minHealthyPercent: 0,
 maxHealthyPercent: 100,
 });

 // --- Outputs ---
 new cdk.CfnOutput(this, 'ClusterName', { value: cluster.clusterName });
 new cdk.CfnOutput(this, 'BucketName', { value: knowledgeBucket.bucketName });
 new cdk.CfnOutput(this, 'EfsId', { value: fileSystem.fileSystemId });
 }
}

2.3 Key Design Decisions in This Stack

Choice	Rationale
`allowAllOutbound: false` + explicit 443	Least privilege. Only HTTPS traffic leaves the container.
`efs.LifecyclePolicy.AFTER_30_DAYS`	Cold memories move to cheaper IA storage automatically.
`removalPolicy: RETAIN` on EFS	A `cdk destroy` won’t wipe your agent’s memory.
`enableExecuteCommand: true`	Allows `aws ecs execute-command` to SSH into the container for debugging.
`minHealthyPercent: 0`	Allows full replacement of the single task during deploys (no spare capacity needed).
Health check `CMD-SHELL true`	No HTTP port exists (Socket Mode only). We just need liveness.
Bedrock resource ARN with `*` region	Cross-region inference profiles can route to any region.

2.4 Deploy Infrastructure

1
2
3
4
5
6
7
8


# Create the ECR repository first (one-time)
aws ecr create-repository --repository-name hermes-agent --region us-east-1

# Bootstrap CDK (first time only)
npx cdk bootstrap

# Deploy
npx cdk deploy

2.5 Store Your Slack Tokens

After deployment creates the secrets, populate them:

1
2
3
4
5
6
7


aws secretsmanager put-secret-value \
 --secret-id hermes/slack-bot-token \
 --secret-string "xoxb-your-bot-token-here"

aws secretsmanager put-secret-value \
 --secret-id hermes/slack-app-token \
 --secret-string "xapp-your-app-token-here"

Step 3: Docker Image

3.1 Dockerfile

Create a docker/ directory with this Dockerfile:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


FROM python:3.11-slim AS base

# Optional: custom CA certificate injection (for corporate proxies)
ARG CUSTOM_CA_CERT_BASE64
RUN if [ -n "$CUSTOM_CA_CERT_BASE64" ]; then \
 echo "$CUSTOM_CA_CERT_BASE64" | base64 -d > /usr/local/share/ca-certificates/custom.crt && \
 update-ca-certificates; \
 fi

# System dependencies
RUN apt-get update && apt-get install -y --no-install-recommends \
 curl git ripgrep ca-certificates unzip \
 && rm -rf /var/lib/apt/lists/*

# AWS CLI v2 (for S3 sync in entrypoint)
RUN curl -sS "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" \
 && unzip -q awscliv2.zip && ./aws/install && rm -rf aws awscliv2.zip

# Node.js 20 (required for MCP servers which run via npx)
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
 && apt-get install -y nodejs \
 && rm -rf /var/lib/apt/lists/*

# Install uv (fast Python package manager) and Hermes Agent
ENV SSL_CERT_FILE=/etc/ssl/certs/ca-certificates.crt
ENV REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt
RUN curl -LsSf https://astral.sh/uv/install.sh | sh \
 && /root/.local/bin/uv pip install --system \
 "hermes-agent[all]" \
 slack-bolt \
 slack-sdk \
 "anthropic[bedrock]>=0.39.0"
ENV PATH="/root/.local/bin:$PATH"

# Non-root user (UID 1000 matches EFS access point)
RUN useradd -m -u 1000 hermes
USER hermes
WORKDIR /home/hermes

ENV HERMES_HOME=/data/hermes

# Copy configuration and entrypoint
COPY --chown=hermes:hermes config.yaml /home/hermes/config.yaml
COPY --chown=hermes:hermes --chmod=755 entrypoint.sh /home/hermes/entrypoint.sh

ENTRYPOINT ["/home/hermes/entrypoint.sh"]

3.2 Why Each Layer

python:3.11-slim: Small base, fewer CVEs than full image
ripgrep: Hermes uses it for fast text search in knowledge files
AWS CLI v2: The entrypoint syncs knowledge from S3 at runtime
Node.js 20: MCP servers (like Jira, GitHub integrations) run via npx
uv: 10–100x faster than pip for package installation
hermes-agent[all]: Full agent framework with all extras (memory, MCP, vision, audio)
anthropic[bedrock]: Enables Bedrock as the inference provider (IAM auth, no API key needed)
UID 1000: Matches the EFS access point — files written by the container are owned correctly

3.3 Build and Push

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


cd docker/

# Build (use --platform on Apple Silicon)
docker build --platform linux/amd64 -t hermes-agent:latest .

# Login to ECR
aws ecr get-login-password --region us-east-1 | \
 docker login --username AWS --password-stdin \
 <YOUR_ACCOUNT_ID>.dkr.ecr.us-east-1.amazonaws.com

# Tag and push
docker tag hermes-agent:latest \
 <YOUR_ACCOUNT_ID>.dkr.ecr.us-east-1.amazonaws.com/hermes-agent:latest
docker push \
 <YOUR_ACCOUNT_ID>.dkr.ecr.us-east-1.amazonaws.com/hermes-agent:latest

Apple Silicon note: The --platform linux/amd64 flag is required. Fargate only supports x86_64 images. Cross-compilation adds ~2 minutes to build time.

Step 4: Configuration

Create docker/config.yaml:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51


model:
 provider: bedrock
 default: us.anthropic.claude-sonnet-4-6  # or claude-opus-4-7 for best quality

agent:
 max_turns: 50
 reasoning_effort: medium
 system_prompt: |
 You are a helpful AI assistant. You have access to files on disk
 and can execute terminal commands to find information.

 When asked a question:
 1. Check if relevant files exist in /data/hermes/knowledge/ or /data/hermes/projects/
 2. Read those files using terminal commands
 3. Synthesize your answer from what you find
 4. If you cannot find information, say so explicitly

memory:
 memory_enabled: true
 user_profile_enabled: true
 memory_char_limit: 2200
 user_char_limit: 1375

terminal:
 backend: local
 timeout: 180
 cwd: /data/hermes # CRITICAL: must match your EFS mount path

compression:
 enabled: true
 threshold: 0.50
 target_ratio: 0.20

display:
 streaming: false
 show_cost: true

security:
 redact_secrets: true

gateway:
 slack:
 enabled: true

# Optional: add MCP servers for external tool integrations
# mcp_servers:
# github:
# command: npx
# args: ["-y", "@modelcontextprotocol/server-github"]
# env:
# GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

Configuration Deep Dive

Field	What It Does	Why It Matters
`model.provider: bedrock`	Use AWS Bedrock for inference	IAM auth, no API key management
`terminal.cwd: /data/hermes`	Working directory AND context discovery root	If wrong, the agent loses all project context
`compression.enabled`	Compresses long conversations	Prevents context window overflow in extended sessions
`gateway.slack.enabled`	Activates Slack Socket Mode listener	The whole point of this deployment
`memory_enabled`	Persists learnings across conversations	Agent improves over time, remembers preferences
`reasoning_effort: medium`	Balances quality and cost	Use `high` for complex multi-step tasks

Critical: terminal.cwd serves a dual purpose. It sets the working directory for terminal commands AND is the starting point for discovering .hermes.md (your project context file). If this doesn’t point to your EFS mount, the agent has no project context.

Step 5: The Entrypoint Script

Create docker/entrypoint.sh:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65


#!/bin/bash
set -e

HERMES_HOME="${HERMES_HOME:-/data/hermes}"

# Initialize HERMES_HOME (always update config from image)
mkdir -p "$HERMES_HOME/memories" "$HERMES_HOME/skills"
cp /home/hermes/config.yaml "$HERMES_HOME/config.yaml"

# S3 knowledge sync function
sync_knowledge() {
 if [ -z "$KNOWLEDGE_BUCKET" ]; then return; fi

 echo "[$(date -u +%H:%M:%S)] Syncing knowledge from s3://$KNOWLEDGE_BUCKET..."

 mkdir -p "$HERMES_HOME/knowledge" "$HERMES_HOME/projects"

 # Sync knowledge notes (--delete removes stale files)
 aws s3 sync "s3://$KNOWLEDGE_BUCKET/knowledge/" "$HERMES_HOME/knowledge/" \
 --delete --quiet 2>/dev/null || true

 # Sync project docs
 aws s3 sync "s3://$KNOWLEDGE_BUCKET/projects/" "$HERMES_HOME/projects/" \
 --quiet 2>/dev/null || true

 # Compose SOUL.md (agent identity, loaded by gateway at startup)
 cat > "$HERMES_HOME/SOUL.md" << 'IDENTITY'
# Hermes — Your Knowledge Assistant

You are a knowledge assistant with access to project documentation and notes stored on disk.

Your primary job is to answer questions by reading files — never from general knowledge alone.

When asked about any topic:
1. Search for relevant files using terminal commands (grep, cat, ls)
2. Read and synthesize your answer from those files
3. If you cannot find the information, say so explicitly

Key paths:
- `/data/hermes/knowledge/` — Topic-specific knowledge notes
- `/data/hermes/projects/` — Project documentation
IDENTITY
 echo "[$(date -u +%H:%M:%S)] SOUL.md composed"
}

# Initial sync at boot
sync_knowledge

# Periodic re-sync every 15 minutes (background)
(
 while true; do
 sleep 900
 sync_knowledge
 done
) &

# Write .env for gateway credentials
cat > "$HERMES_HOME/.env" << EOF
SLACK_BOT_TOKEN=${SLACK_BOT_TOKEN}
SLACK_APP_TOKEN=${SLACK_APP_TOKEN}
GATEWAY_ALLOW_ALL_USERS=true
EOF

# Start gateway in foreground mode
exec hermes gateway run

Boot Sequence Explained

Container Start
│
├─ 1. Create directories: memories/, skills/
├─ 2. Copy config.yaml from image → EFS (always fresh)
├─ 3. S3 sync: download knowledge/, projects/
├─ 4. Compose SOUL.md (agent identity)
├─ 5. Start background sync loop (every 15 min)
├─ 6. Write .env (Slack tokens)
└─ 7. exec hermes gateway run
│
└─ Connects to Slack via Socket Mode
Listens for DMs and @mentions

Why always overwrite config.yaml? EFS is persistent. If you deployed a bad config once, it would stick forever. By always copying from the image, you guarantee that a fresh deploy always brings fresh configuration.

Why exec? The exec command replaces the shell process with the Hermes gateway. This means signals (SIGTERM from ECS during deployment) propagate directly to Hermes, enabling graceful shutdown.

Why || true on S3 sync? If the bucket is empty or the agent starts before knowledge is uploaded, we don’t want the container to crash. It will try again in 15 minutes.

Step 6: The Knowledge System

This is what makes the deployment truly useful. Hermes loads context from three independent slots:

Slot	File	Char Limit	Purpose
Identity	`SOUL.md`	20,000	Who the agent is. Personality, key behaviors, available paths.
Project Context	`.hermes.md`	20,000	Domain knowledge. Loaded via `terminal.cwd` discovery.
System Prompt	`config.yaml`	None	Behavioral rules. Task-specific instructions.

How SOUL.md Works

When the gateway starts, it looks for SOUL.md in $HERMES_HOME. This file defines the agent’s identity — think of it as the “who you are” prompt. It’s always loaded into every conversation, capped at 20,000 characters.

Our entrypoint composes it at boot from a heredoc. You could also sync it from S3 for dynamic updates.

How .hermes.md Works (Optional)

If you create a file called .hermes.md at the terminal.cwd path (/data/hermes/.hermes.md), Hermes will automatically discover and load it as project context. This is useful for providing high-level documentation that should always be in context.

Knowledge Update Workflow (No Redeploy)

1. Upload files to S3:
aws s3 sync ./my-docs/ s3://hermes-knowledge-<ACCOUNT_ID>/knowledge/
2. Wait 15 minutes (background sync picks it up)
— OR —
Force immediate pickup:
aws ecs update-service --cluster hermes-agent \
--service hermes-gateway --force-new-deployment

This is the key operational advantage: your agent’s knowledge evolves independently of its container. Write a new doc, upload to S3, and the agent knows about it within 15 minutes.

Step 7: Deploy and Test

7.1 Trigger Deployment

If you already pushed the image and deployed infrastructure:

1
2
3
4


aws ecs update-service \
 --cluster hermes-agent \
 --service hermes-gateway \
 --force-new-deployment

7.2 Watch Logs

1

aws logs tail /ecs/hermes-agent --since 5m --follow

Success indicators:

[14:30:01] Syncing knowledge from s3://hermes-knowledge-...
[14:30:05] SOUL.md composed

If you see the gateway start without errors, the agent is live.

7.3 Talk to Your Agent

Open Slack, find your bot in the Apps section (or DM it directly), and send:

Hello! What can you do?

You should get a response from Claude describing its capabilities.

7.4 Debug with ECS Exec

If something goes wrong, shell into the running container:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# Get the task ID
TASK_ID=$(aws ecs list-tasks --cluster hermes-agent \
 --service-name hermes-gateway --query 'taskArns[0]' --output text | \
 awk -F'/' '{print $NF}')

# Shell in
aws ecs execute-command \
 --cluster hermes-agent \
 --task $TASK_ID \
 --container hermes \
 --interactive \
 --command "/bin/bash"

Inside the container, check:

1
2
3
4


cat /data/hermes/config.yaml # Config loaded correctly?
cat /data/hermes/SOUL.md # Identity composed?
ls /data/hermes/knowledge/ # Knowledge synced?
cat /data/hermes/.env # Tokens present?

Troubleshooting

These are all real issues I hit during deployment. Each one cost me 30+ minutes the first time.

1. SSL/TLS Errors During Docker Build

Symptom: pip install or curl fails with SSL certificate problem: unable to get local issuer certificate

Root Cause: Corporate VPN or proxy injecting a custom CA certificate that Docker’s build environment doesn’t trust.

Solution: Pass your custom CA cert as a base64 build arg:

1
2
3
4


docker build \
 --build-arg CUSTOM_CA_CERT_BASE64=$(base64 < /path/to/your-ca-cert.pem) \
 --platform linux/amd64 \
 -t hermes-agent:latest .

Also: the ENV SSL_CERT_FILE and ENV REQUESTS_CA_BUNDLE in the Dockerfile handle Rust-based tools (like uv) that maintain their own cert store.

2. S3 Sync Silently Fails

Symptom: Knowledge files never appear on EFS, but no errors in logs (because of || true).

Root Cause: IAM task role has s3:GetObject but is missing s3:ListBucket. The sync command needs to list before it can download.

Solution: Use CDK’s bucket.grantRead() which grants both s3:GetObject* and s3:ListBucket. If you crafted IAM manually, add both.

3. ECS Task Stuck in PROVISIONING

Symptom: Task never reaches RUNNING status. Stays in PROVISIONING for minutes, then fails.

Root Cause: Security group doesn’t allow NFS traffic (port 2049) between the Fargate task and the EFS file system.

Solution: In CDK, use fileSystem.connections.allowDefaultPortFrom(taskSg). This automatically creates the correct security group rule. If you’re using CloudFormation directly, add an ingress rule on the EFS security group allowing port 2049 from the task security group.

4. Slack “missing_scope” Errors

Symptom: Bot connects but logs show 'error': 'missing_scope', 'needed': 'im:history'.

Root Cause: Scopes were added AFTER the app was already installed to the workspace. Scope changes require re-installation.

Solution: After adding new scopes in the Slack app settings, go to OAuth & Permissions and click “Reinstall to Workspace”. This regenerates the bot token with the new scopes.

5. Agent Has No Project Context (.hermes.md Not Loading)

Symptom: Agent responds but seems to have no knowledge of your projects. SOUL.md loads fine, but .hermes.md is ignored.

Root Cause: terminal.cwd in config.yaml doesn’t point to where .hermes.md lives. Hermes discovers .hermes.md by walking up from terminal.cwd.

Solution: Ensure terminal.cwd: /data/hermes in your config.yaml AND that .hermes.md exists at /data/hermes/.hermes.md.

6. MCP Server Fails to Start

Symptom: "Failed to start MCP server" in logs. Agent works but external tools are unavailable.

Root Cause: Node.js is not installed in the container. MCP servers run via npx which requires Node.js.

Solution: Include the Node.js installation step in your Dockerfile. Also verify outbound HTTPS works (npx downloads packages from npm registry on first run).

7. Bedrock AccessDeniedException

Symptom: Agent connects to Slack but every response is an error. Logs show AccessDeniedException from Bedrock.

Root Cause: IAM policy restricts Bedrock access to a single region, but cross-region inference profiles (the us. prefix models) route to any region.

Solution: Use wildcard * for the region portion of the Bedrock resource ARN:

arn:aws:bedrock:*::foundation-model/anthropic.*
arn:aws:bedrock:*:<ACCOUNT>:inference-profile/*

8. Container Keeps Restarting (Health Check Failure)

Symptom: ECS repeatedly stops and restarts the task. Logs show “container marked unhealthy.”

Root Cause: Default health check expects an HTTP response, but Hermes has no HTTP port — it only uses outbound WebSocket (Socket Mode).

Solution: Use CMD-SHELL true as the health check command. This always passes. You rely on the circuit breaker for actual failure detection (crash loop protection).

9. Config Changes Not Taking Effect

Symptom: You updated config.yaml, rebuilt the image, pushed, and force-deployed. But the agent still behaves with old config.

Root Cause: The Hermes gateway caches the AIAgent object at startup. Even though the entrypoint overwrites config.yaml on EFS, the gateway only reads it once.

Solution: Force a new deployment: aws ecs update-service --force-new-deployment. This kills the old task and starts fresh. Knowledge changes (S3 files read at query time) don’t need restarts — only config changes do.

Cost Breakdown

Resource	Monthly Cost
ECS Fargate (512 CPU, 1024 MiB, 24/7)	~$15
NAT Gateway (fixed hourly + data transfer)	~$35–45
EFS (1 GB, mostly Infrequent Access)	~$0.50
S3 (10 MB knowledge files)	~$0.01
Secrets Manager (2 secrets)	~$0.80
CloudWatch Logs (2 weeks retention)	~$1–3
Subtotal (infrastructure)	~$55–65
Bedrock inference (varies by usage)	$5–100+

Cost Optimization Tips

NAT Gateway is the biggest fixed cost. For personal projects, consider:

A NAT Instance on t4g.nano (~$4/month) instead of a managed NAT Gateway
Or deploy in a public subnet with a public IP (simpler but less secure)

Use Sonnet instead of Opus for routine queries. Opus costs 5–10x more per token. Save Opus for complex reasoning tasks.

EFS Infrequent Access automatically moves files untouched for 30 days to cheaper storage (from $0.30/GB to $0.025/GB).

Next Steps

Once your agent is running, here’s what to explore:

Add MCP Servers — Give your agent tools. Jira, GitHub, Linear, databases — anything with an MCP-compatible server. Add them to the mcp_servers: section of config.yaml.

Automate Knowledge Updates — Set up a CI/CD pipeline that syncs documentation to S3 on every merge. Your agent’s knowledge stays current without manual intervention.

Multi-Agent Architecture — Run a second Hermes instance with a different SOUL.md and config. One agent for engineering questions, another for project management, another for code review.

Scheduled Tasks — Use EventBridge to periodically invoke prompts. Daily standup summaries, weekly reports, automated checks.

Access Control — Set GATEWAY_ALLOW_ALL_USERS=false and configure an allowlist. Restrict which Slack users can interact with the agent.

Wrapping Up

What we’ve built is a production-grade AI assistant deployment: always-on, team-accessible, with persistent memory and a self-updating knowledge base. The Socket Mode architecture eliminates the typical networking headaches of Slack bots, and the S3 knowledge sync means your agent gets smarter without redeployments.

The entire infrastructure is defined as code (CDK), the container is reproducible (Docker), and the knowledge system is just files in a bucket. No vendor lock-in beyond AWS Bedrock for inference — and even that could be swapped by changing model.provider in config.yaml.

If you want to see the Hermes Agent project: github.com/NousResearch/hermes-agent.

Happy deploying.

Personal AWS Cost Guardrails: Budget Alerts, Auto-Stop, and Anomaly Detection on a Hobby Account

Yoonsoo Park — Mon, 30 Mar 2026 12:35:00 -0400

There’s a recurring genre of AWS war story — “I left a script running, woke up to a $4,000 bill, AWS support waived it.” It’s a real risk on a hobby account: you don’t have an org-level SCP, you don’t have a FinOps team, and one misconfigured loop on Bedrock or a forgotten EC2 instance can quietly run for a week.

So I sat down and built the smallest set of guardrails that would actually stop me, not just notify me. Three layers. All deployable from one CloudFormation stack except the last one, which has a constraint AWS doesn’t document well.

What I’m protecting against

Steady drift — I forget the EC2 instance is up, it racks up $30 over a month. Annoying, not catastrophic.
Surprise spike — I push a buggy script that hammers Bedrock or starts a too-big instance. Could be hundreds of dollars in hours.
Slow leak — Some service I provisioned a year ago is still billing me $3/day. Death by a thousand papercuts.

Different time horizons need different tools.

Layer 1 — Budget alerts (the slow drift)

AWS Budgets fires email alerts at thresholds against a monthly cost target. Not real-time — Budgets evaluates roughly every 8–12 hours — but cheap and zero-maintenance.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


MonthlyBudget:
 Type: AWS::Budgets::Budget
 Properties:
 Budget:
 BudgetName: monthly-cost-budget
 BudgetType: COST
 TimeUnit: MONTHLY
 BudgetLimit:
 Amount: 40
 Unit: USD
 NotificationsWithSubscribers:
 - Notification:
 NotificationType: ACTUAL
 ComparisonOperator: GREATER_THAN
 Threshold: 50
 ThresholdType: PERCENTAGE
 Subscribers:
 - SubscriptionType: SNS
 Address: !Ref CostAlertTopic
 - Notification:
 NotificationType: ACTUAL
 ComparisonOperator: GREATER_THAN
 Threshold: 80
 ThresholdType: PERCENTAGE
 Subscribers:
 - SubscriptionType: SNS
 Address: !Ref CostAlertTopic
 - Notification:
 NotificationType: ACTUAL
 ComparisonOperator: GREATER_THAN
 Threshold: 100
 ThresholdType: PERCENTAGE
 Subscribers:
 - SubscriptionType: SNS
 Address: !Ref CostAlertTopic

50% / 80% / 100% is the common shape. The 50% notification is the one that’s actually useful — if I’m halfway through the month and at 50%, I’m tracking. If I’m one week in and at 50%, something is wrong.

Layer 2 — Auto-stop Lambda (the spike safety net)

Email alerts at 100% are nice but I’m not going to read email at 2am. So the 100% threshold also fires an SNS message that triggers a Lambda, which stops every running EC2 instance tagged with AutoStop=true.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


AutoStopFunction:
 Type: AWS::Lambda::Function
 Properties:
 FunctionName: cost-monitor-auto-stop
 Runtime: python3.13
 Handler: index.handler
 Role: !GetAtt AutoStopRole.Arn
 Timeout: 60
 Code:
 ZipFile: |
 import boto3
 ec2 = boto3.client('ec2')
 def handler(event, context):
 r = ec2.describe_instances(Filters=[
 {'Name': 'tag:AutoStop', 'Values': ['true']},
 {'Name': 'instance-state-name', 'Values': ['running']},
 ])
 ids = [i['InstanceId'] for res in r['Reservations'] for i in res['Instances']]
 if ids:
 ec2.stop_instances(InstanceIds=ids)
 return {'stopped': ids}

AutoStopSubscription:
 Type: AWS::SNS::Subscription
 Properties:
 TopicArn: !Ref CostAlertTopic
 Protocol: lambda
 Endpoint: !GetAtt AutoStopFunction.Arn

This is not a real-time circuit breaker. Budgets evaluates every 8–12 hours, so the auto-stop only kicks in within that window. If you launch a p4d.24xlarge and it costs $40/hour, you can blow past your $40 monthly budget in one hour and Budgets won’t notice until the next evaluation cycle.

The auto-stop is for the case where you’ve been gradually burning toward your monthly limit and want a “no, really, stop spending” backstop. For genuine spike protection, you need Layer 3.

The IAM role is small — just ec2:DescribeInstances and ec2:StopInstances, scoped to the account. No reason to grant Start on the auto-stop role; restarting is a manual decision.

Layer 3 — Cost Anomaly Detection (the spike detector)

This is the one that catches “you launched something weird two hours ago.” Cost Anomaly Detection (CAD) evaluates roughly daily on actual usage, looks for statistical anomalies vs. your historical baseline per service, and emails you when one service’s daily spend deviates significantly.

The trick: you can’t fully manage CAD from CloudFormation if you already have a manually-created monitor. AWS allows exactly one DIMENSIONAL/SERVICE anomaly monitor per account. If you click around in the console and create one, then later try to create one in CloudFormation:

AlreadyExistsException: AnomalyMonitor already exists.

The fix is one of:

Delete the manual one, then create via CloudFormation.
Skip CloudFormation, manage CAD by hand via the console.
Import the existing resource into your stack (aws cloudformation create-change-set --change-set-type IMPORT ...).

I went with option 2 because CAD is set-and-forget. The monitor lives outside the stack; the stack manages the budget + auto-stop + SNS topic.

If you do go via CloudFormation, two more gotchas:

ThresholdExpression is a JSON string, not a YAML object. CFN’s parser will accept the YAML and then fail at deploy:

1
2
3
4
5
6
7
8
9


# correct
ThresholdExpression: '{"Dimensions":{"Key":"ANOMALY_TOTAL_IMPACT_ABSOLUTE","MatchOptions":["GREATER_THAN_OR_EQUAL"],"Values":["5"]}}'

# wrong — fails EarlyValidation
ThresholdExpression:
 Dimensions:
 Key: ANOMALY_TOTAL_IMPACT_ABSOLUTE
 Values: ['5']
 MatchOptions: ['GREATER_THAN_OR_EQUAL']

Frequency: IMMEDIATE only works with SNS subscribers. If you want email straight to your inbox, the supported frequencies are DAILY and WEEKLY. I went with DAILY and a $5 absolute-impact threshold — anything that bumps a single service by $5 in a day is something I want to know about within 24 hours.

What this catches and what it doesn’t

Scenario	Caught by	Latency
Forgotten EC2 instance, ~$30 over a month	Budget at 50% / 80%	~12 hours
Bedrock loop bug, $200 in one afternoon	Anomaly Detection	~24 hours
`p4d` launched accidentally	None of the above, fast enough	Hours
Slow leak: $3/day for a year	Anomaly Detection threshold (if $5+)	DAILY email

Honest assessment: a determined accident in a single hour can still hurt. AWS doesn’t really offer real-time auto-stop at any reasonable price point — Budgets is the closest thing and it’s not real-time. If you genuinely need spike protection on the order of minutes, your options are (a) provision through Service Catalog with hard-coded instance type allowlists, (b) put an SCP on a proper org account, or (c) keep most of your spend on a fixed-cost subscription (Reserved/Savings Plans) so the variable portion can’t run away.

For a hobby account: this three-layer setup is what I’d call “good enough that I don’t lose sleep, cheap enough that it costs me nothing on top of what I’m already spending.”

Pitfalls I actually hit

AlreadyExists on the anomaly monitor. If you’ve ever clicked “set up anomaly detection” in the console, you have a DIMENSIONAL/SERVICE monitor and CFN can’t make a second one. Either import it or skip CFN for CAD.
ThresholdExpression shape. Must be a JSON-encoded string. CFN templates accept YAML for most properties so this looks like a typo, not a constraint.
Frequency: IMMEDIATE with email. Doesn’t work. Use SNS-then-email if you want IMMEDIATE; use DAILY/WEEKLY for direct email.
Auto-stop ≠ circuit breaker. Budgets is not real-time. If you write a tight Bedrock loop, the auto-stop fires hours after you’ve already spent the money.
Tag your stoppable instances. The Lambda filters on AutoStop=true. If you forget the tag, the Lambda runs successfully and stops nothing. Tag every personal EC2 instance with AutoStop=true by default; remove the tag explicitly when you want something to keep running.
Restart is manual on purpose. The Lambda has no ec2:StartInstances. Restarting an instance after auto-stop should be a conscious “okay, I know what’s running and why” decision, not an automatic recovery.

What to do

If you have a personal AWS account and you don’t have at least Layer 1 (a budget with email alerts), set that up today — it’s ten minutes in the console, free, and prevents the steady-drift class of problem.

If you’re running anything that bills by the hour (EC2, RDS, OpenSearch, GPU anything), add Layer 2. The Lambda is twenty lines and a tag.

If you’re using usage-billed services where one bug can spike fast (Bedrock, Lambda invocation count, S3 request count), add Layer 3 — DAILY anomaly emails at a $5 absolute threshold catch the “what is this charge” stuff before it becomes a “what was this charge” conversation.

Three layers, ~20 minutes total, zero ongoing cost. Worth it.

AWS Strands vs LangGraph on Bedrock AgentCore: Lessons from Building an Agentic Platform

Yoonsoo Park — Sat, 28 Feb 2026 00:00:00 +0000

Comparing AWS Strands and LangGraph through hands-on PoC experience on Amazon Bedrock AgentCore — real cold start numbers, a three-tier tool architecture pattern, and the async tool gap that caught us off guard.

AWS Strands Agents SDK | LangGraph Documentation | Amazon Bedrock AgentCore

Review note (2026-08-28): The measurements and deployment observations below are a February 2026 PoC snapshot. Strands, LangGraph, and AgentCore release independently; re-check the linked documentation and package versions before copying the code into a new deployment.

Most framework comparisons stop at “hello world.” You read them, nod along, then hit a wall that the blog never mentioned. This post is the opposite of that. I want to share what actually happened when we ran both AWS Strands and LangGraph through PoCs on a financial SaaS platform, picked one, and started building a real multi-tool agent with it. Spoiler: we found a gap that made us rethink our confidence level.

The Setup: Why We Needed an Agent Framework

Our platform is 100% AWS-native. The primary execution environment is Amazon Bedrock AgentCore — think of it as a managed runtime for AI agents with built-in memory, tool routing, and IAM-based auth. We needed to build agentic workflows that could handle 51 backend actions (knowledge base search, document extraction, custom AI actions, etc.) for financial domain customers.

Two candidates made the shortlist:

LangGraph (LangChain ecosystem) — explicit state machines, large community, mature docs
AWS Strands (AWS-native) — autonomous agent loop, @tool decorators, minimal boilerplate

We PoC’d both, picked Strands, and started building a real agent with 25+ tools on it. The story isn’t as simple as “X is better.” It’s more like “X works great until you hit this wall.”

What Killed LangGraph in Our PoC

I want to be clear: LangGraph is a solid framework. The state machine model gives you explicit control over every step — when the LLM gets called, when tools execute, how results route. For complex multi-step workflows, that’s powerful. But in our environment, it never got the chance to show that.

The 30-Second Observation (Historical)

During this PoC we observed a 30-second initialization problem when native dependencies were installed during startup. That observation should not be copied as a universal AgentCore contract: current AgentCore documentation exposes configurable runtime lifecycle settings and does not document a blanket 30-second initialization limit. LangGraph still relies on packages such as numpy and pydantic-core, so build and measure the image for your selected architecture rather than installing native wheels during a cold start.

The workaround exists: use Docker-based Lambda build containers (public.ecr.aws/sam/build-python3.11), pre-compile ARM64 wheels, bundle them into your CDK code assets before deployment. It works. But it also means every code change goes through a Docker build step that kills your iteration speed. For a PoC where you’re experimenting rapidly, that friction adds up fast. Trust me, we tried to make it work for a while before moving on.

We confirmed this wasn’t a one-time issue in our PoC — native dependency installation remained the fundamental constraint for that build. LangGraph remained blocked for our use case at that snapshot, unless we moved compilation into the image build or changed the dependency footprint. Re-test this conclusion against the current runtime and package versions.

The Ecosystem Advantage is Real Though

I want to acknowledge something: LangGraph has significantly better documentation and community support. It launched earlier, so there are more reference implementations, more Stack Overflow answers, more patterns to copy. When we hit issues with Strands, the answer was often “read the Bedrock docs and figure it out.” With LangGraph, someone had usually already solved it. That gap matters during the learning curve. It just didn’t outweigh the deployment blocker for us.

Strands in Practice: What We Actually Built

Here’s our agent entry point. The whole thing:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


# agent.py — 26 lines total
from strands import Agent
from strands.models import BedrockModel

model = BedrockModel(
 model_id="global.anthropic.claude-sonnet-4-6",
 temperature=0.1,
 streaming=True,
)

agent = Agent(model=model, tools=tools, system_prompt=prompt)
result = agent(user_input) # Autonomous loop handles everything

That’s it. No state machine definition, no node compilation, no conditional edge routing. The agent loop decides when to call tools, when to respond, when to ask for clarification. You hand it tools and a prompt, it figures out the rest.

For comparison, the LangGraph equivalent would need roughly 80-100 lines: state class definition, chatbot node, tools node, conditional edge routing function, graph compilation, and invocation boilerplate.

Cold starts in this PoC? Under 500ms. We used UV bytecode compilation (UV_COMPILE_BYTECODE=1 in our Dockerfile) and measured a prebuilt image with no native dependency compilation. Treat that number as a dated workload measurement, not an AgentCore guarantee.

The Three-Tier Tool Architecture

This is the pattern we landed on through our PoC iterations. It wasn’t planned upfront — it emerged from hitting real constraints around latency, security, and multi-tenant isolation:

┌─────────────────────────────────────────────┐
│ Strands Agent (Claude Sonnet 4) │
└──────────────────┬──────────────────────────┘
│
┌─────────────┼─────────────────┐
▼ ▼ ▼
┌─────────┐ ┌──────────┐ ┌──────────────┐
│ Direct │ │ Gateway │ │ Tool │
│ Tools │ │ Tools │ │ Wrappers │
│ (15×) │ │ (10×) │ │ │
└─────────┘ └──────────┘ └──────────────┘
│ @tool │ MCP proto │ Auto-inject
│ decorator │ Lambda │ tenant_id
│ In-process │ backends │ Hidden from
│ execution │ IAM auth │ LLM context
└────────────┴────────────┴───────────────

Why three tiers?

Direct Tools run inside the agent container. They’re simple functions decorated with @tool — Strands auto-extracts the JSON schema from the function signature and docstring. No manual schema definition needed. We have 15 of these for low-latency, same-tenant operations. Average: ~24 lines per tool including docstring and serialization.

Here’s what a direct tool looks like (simplified from our actual implementation):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


@tool
def search_knowledge_base(query: str, max_results: int = 5) -> str:
 """Search the knowledge base for relevant documents."""
 client = boto3.client("bedrock-agent-runtime")
 response = client.retrieve(
 knowledgeBaseId=os.environ["KB_ID"],
 retrievalQuery={"text": query},
 retrievalConfiguration={
 "vectorSearchConfiguration": {"numberOfResults": max_results}
 },
 )
 results = [
 {"text": r["content"]["text"], "score": r["score"]}
 for r in response["retrievalResults"]
 ]
 return json.dumps({"results": results, "count": len(results)})

~16 lines. In LangGraph, the same tool needs a state TypedDict, a node function, graph wiring, and compilation — roughly 40-50 lines. Multiply that by 15 tools and the difference is significant.

Gateway Tools go through MCP (Model Context Protocol) to Lambda backends with SigV4 authentication. These handle cross-tenant operations or operations that need their own execution context. We define them in CDK and the MCP client discovers them at runtime.

Tool Wrappers solve a subtle but important problem: tenant isolation. The LLM should never see or manipulate tenant_id directly — that’s a security boundary. Wrappers auto-inject the tenant ID into tool calls before they hit the backend, keeping it invisible to the model:

1
2
3
4
5
6
7


# Simplified wrapper pattern
def wrap_tool_with_tenant(tool_fn, tenant_id):
 @wraps(tool_fn)
 def wrapped(**kwargs):
 kwargs["tenant_id"] = tenant_id # Injected, never from LLM
 return tool_fn(**kwargs)
 return wrapped

This pattern was born from a real security review, not from upfront design. The LLM was occasionally hallucinating tenant IDs in early testing — yeah, it just made up tenant IDs that looked plausible. In a financial platform, that’s a nightmare. Wrappers killed that problem entirely.

The Bedrock Memory Integration

One thing that “just worked” was Bedrock Memory. Our configuration:

Semantic indexing: Auto-retrieve relevant context from past conversations
Summarization: Compress long conversation histories so the context window stays manageable
Retention: 90 days
Last K turns: Load the 10 most recent turns on agent initialization

We use a HookProvider pattern (more on hooks below) to load memory on session start. The agent gets conversation context without any explicit retrieval code — Bedrock handles the vector search and summarization behind the scenes.

This is one of Strands’ strongest selling points compared to LangGraph: the managed infrastructure handles memory, auth, and tool routing. With LangGraph, you’d wire each of these manually.

The Gotchas Nobody Tells You About

Building a real agent teaches you things that docs don’t.

Container Tool Caching (High Impact)

After deploying a new Gateway Lambda function, the running AgentCore container still has stale tool definitions. The MCP client caches tool schemas at container startup. Your only option: wait 60-90 seconds for the container idle timeout to trigger a restart.

This sounds minor. It isn’t. When you’re iterating on a Gateway tool — deploy, test, see wrong behavior, realize it’s stale, wait, test again — you lose 2-3 minutes per cycle. Over a day of active development, that adds up.

Response Format Quirk

agent.result.message returns a dict, not a string:

1
2
3
4
5


# What you might expect
result.message # "Here's the extracted text..."

# What you actually get
result.message # {"role": "assistant", "content": [{"text": "Here's the extracted text..."}]}

Every caller has to extract content[*].text blocks. It’s a small thing, but when you’re debugging at midnight wondering why your response is empty… you remember this one. Wish the SDK just handled it.

boto3 and SDK compatibility

The Strands and AgentCore SDK surfaces move independently. Keep boto3/botocore and the Strands packages on versions supported by the current AgentCore deployment guide; do not preserve the old boto3 >= 1.42.54 pin from this PoC as a universal requirement. If another service pins an older SDK, isolate the environments and run the current compatibility checks before deployment.

The Hard Part: The Async Tool Gap

Now for the finding that changed my confidence level from “high” to “medium.” This is where Strands’ simplicity becomes a real limitation.

The Problem

Our platform has dozens of backend actions. Roughly half are synchronous. The other half are asynchronous — things like Textract document extraction (2-5 minutes for large PDFs), async LLM inference, document intelligence processing. The async ones use a robust infrastructure: job tracking, Step Functions for polling, EventBridge for completion events.

But Strands’ autonomous loop completes in a single conversation turn. When a tool returns {"status": "pending"}, the agent receives it, tells the user “processing…”, and the conversation ends. There’s no built-in mechanism to poll, wait, or resume.

Here’s what actually happens in practice:

User: "Extract text from this document"
Agent: calls extract_document("file_id_123")
→ returns {"status": "pending", "job_id": "abc-def-..."}
Agent: "Text extraction is in progress. Please check back later."
[Agent loop ends — no mechanism to retry or wait]
User: "Is it done yet?"
Agent: calls check_job_status("abc-def-...")
→ returns {"status": "pending"}
Agent: "Still processing..."
User: [waits another minute, asks again]
Agent: calls check_job_status("abc-def-...")
→ returns {"status": "succeeded", "output": "..."}
Agent: "Here's the extracted text!"

The user has to manually poll. That’s not a great experience.

Why This Matters More Than It Seems

During the early PoC, this felt like a minor issue — we mostly exposed sync tools first. But looking at our actual backend, roughly half of our actions are asynchronous. Things like document processing via Textract, async LLM inference, batch data operations — these are all long-running jobs that return pending and complete later.

Most of these aren’t exposed to the Strands agent yet. But as we expand the tool surface toward production, this architectural gap becomes central.

The Architecture Disconnect

Our backend already has great async infrastructure. The pattern is common in AWS: when a tool kicks off a long-running job (e.g., Textract, async inference), it returns immediately with {"status": "pending"} and a job ID. A Step Functions state machine then polls for completion, updates the job status, and stores the result.

Tool invocation
│
├─ Sync job? → execute → status: "succeeded" → return
│
└─ Async job? → validate → status: "pending"
│
▼
Step Functions
├─ Poll every N seconds
├─ Update status: pending → running → succeeded
└─ Store result

The problem is that Strands doesn’t know about any of this. The agent calls the tool, gets back {"status": "pending"}, and moves on. Step Functions completes the job in the background, but the agent is long gone.

┌─────────────────────────────────┐
│ Strands Agent │
│ call tool() │
│ → {"status": "pending"} │
│ → tells user "processing..." │
│ → loop ends ← HERE │
└────────────────┬────────────────┘
│ (disconnected)
┌────────────────▼────────────────┐
│ Backend Async Infrastructure │
│ Step Functions polling │
│ Job: pending → succeeded │
│ (agent is already gone) │
└─────────────────────────────────┘

Where LangGraph Would Shine

This is, honestly, where LangGraph’s state machine model is genuinely superior. You can define a polling loop as a conditional edge:

1
2
3
4
5


workflow.add_conditional_edges("poll_status", route_by_status, {
 "check_again": "poll_status", # ← loops back
 "completed": "summarize",
 "timeout": END,
})

The state machine maintains job_id, retries, status across iterations. One user request, one final result. No manual polling.

Our Workaround Strategy

We’re not switching frameworks over this. Instead, we’re taking a phased approach:

Right now: Accept manual polling for the few async tools we’ve exposed. Not ideal, but the frequency is low enough that users tolerate it.

Next quarter: Implement EventBridge + Bedrock Memory integration. When an async job completes, an EventBridge rule triggers a Lambda that writes the result to Bedrock Memory with a tagged key. When the user asks again, the agent checks Memory first — one follow-up instead of repeated polling.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


@tool
def extract_document_text(file_id: str) -> str:
 """Start async extraction. Results stored in memory on completion."""
 job_id = start_textract_async(file_id)
 # EventBridge: Textract complete → Lambda → save to Memory
 return json.dumps({
 "status": "processing",
 "message": "Extraction started. Ask me again in a minute for results."
 })

@tool
def check_extraction_result(job_id: str) -> str:
 """Check if extraction completed (reads from Memory first)."""
 result = memory_client.search(tag=f"extraction_{job_id}")
 if result:
 return json.dumps({"status": "completed", "text": result["text"]})
 return json.dumps({"status": check_job_status(job_id)})

Before production: If async tool usage looks like it’ll exceed 60-70% of traffic, we’ll re-evaluate LangGraph. By then, the runtime and framework versions may have changed, so repeat the image-build and lifecycle measurements instead of relying on the historical 30-second observation.

The Numbers

Here’s where the metrics stood in the February 2026 PoC:

Metric	Value
Agent setup code	26 lines (agent.py) + 79 lines (main.py)
Lines per tool (avg)	~24 lines with `@tool` decorator
Tools implemented	25 (15 direct + 10 Gateway)
Cold start	< 500ms
Full CDK deploy	~8-12 min
Container tool refresh	~60-90 sec after Gateway update
Code reduction vs LangGraph	~3× for tool definitions

These are workload-specific measurements, not current service-level objectives. Re-run them after changing the runtime image, region, model, or framework version.

So, Which One Should You Pick?

If you’re deploying on Bedrock AgentCore with mostly synchronous tools, Strands is the clear winner. The developer experience is outstanding — 26 lines for an agent, sub-500ms cold starts, and @tool decorator that eliminates boilerplate. The managed infrastructure (memory, auth, tool routing) saves weeks of wiring.

If your workload is async-heavy — lots of long-running jobs, polling, multi-step workflows with state — LangGraph’s state machine model is architecturally better suited. But you’ll need to solve the AgentCore deployment friction first (Docker pre-compilation, dependency bundling).

If you’re somewhere in the middle like us — mostly sync today, growing async tomorrow — start with Strands and plan your async workarounds early. Don’t wait until half your tools are async to discover the gap like we did.

The honest answer is that there’s no perfect framework yet for this space. Strands trades control for simplicity. LangGraph trades simplicity for control. Both trade-offs have consequences that only show up after you’ve been building with them for a while.

If you’re building agentic workflows on AWS and have questions about any of this, feel free to reach out. I’m still learning too, and the landscape is changing fast. Hopefully this post saves you some of that discovery time we had to go through the hard way.

Why You Should Switch to uv for Python Projects

Yoonsoo Park — Sat, 14 Feb 2026 00:00:00 +0000

If you are a Python developer, you are likely familiar with the fragmented ecosystem of tooling. You use pip for installing packages, venv or virtualenv for environments, pyenv for managing Python versions, and maybe poetry or pip-tools for dependency resolution. It’s a lot to manage.

Enter uv.

Created by Astral (the team behind Ruff), uv is an extremely fast Python package and project manager written in Rust. It’s designed to be a drop-in replacement for pip and pip-tools, but it has evolved into a full-fledged project manager that challenges poetry and pdm.

In this post, I’ll explain why uv is a game-changer and why you should consider switching today.

Why `uv` is a Game Changer

1. Blazing Speed

Yup, it is freaking fast. In many benchmarks, uv is 10-100x faster than pip-tools or poetry for resolution.

2. Unified Toolchain

uv consolidates multiple tools into one. You no longer need separate tools for:

Package Installation (pip)
Environment Management (venv, virtualenv)
Python Version Management (pyenv)
Dependency Locking (pip-compile, poetry lock)
Script Running (pipx)

You can do it all with a single binary.

3. Automatic Python Version Management

This is my favorite feature. If a project requires Python 3.12 but you only have 3.11 installed, tools like poetry will complain. You’d have to go to pyenv, install 3.12, and then tell poetry to use it.

With uv, you just define the required python version in your project. uv will automatically download and install the correct Python version for that project if it’s missing, in an isolated manner (in .venv). No more global Python version conflicts!!

Comparison: uv vs Poetry

If you are currently using Poetry, you might wonder if it’s worth the switch.

Feature	Poetry	uv
Language	Python	Rust
Speed	Slow (dependency resolution can take minutes)	Instant (sub-second resolution)
Python Management	Relies on external tools (pyenv/system)	Built-in (installs Python automatically)
Standards	Uses `pyproject.toml` (standard)	Uses `pyproject.toml` (standard)
Lock File	`poetry.lock`	`uv.lock` (cross-platform)

The biggest pain point with Poetry has always been the dependency resolver speed. uv solves this completely.

Migrating from `requirements.txt`

If you have a legacy project using requirements.txt, migrating to uv is EZ. You don’t have to rewrite everything from scratch.

uv supports installing directly from requirements files, and it gives you two ways to do it:

1. Using `uv pip` (The “pip” way)

If you just want to use uv as a faster pip without changing your workflow:

1

uv pip install -r requirements.txt

This installs packages into your current environment exactly like pip install -r requirements.txt, just much faster.

2. Using `uv add` (The “Project” way)

If you are initializing a new uv project (uv init) and want to import your dependencies:

1

uv add -r requirements.txt

This reads your requirements.txt and adds the dependencies to your pyproject.toml file, effectively migrating your project management to uv.

Common Commands Cheat Sheet

Here are the commands you will use 90% of the time:

Initialize a project:
1

uv init
Add a dependency:
1

uv add requests
Run a script:
1

uv run main.py
Note: uv run will automatically create a virtual environment, install dependencies, and run the script in that isolated environment.
Sync environment:
1

uv sync
Ensures the virtual environment matches the uv.lock file.

`uv add` vs `uv pip install`

It’s important to understand the difference between these two commands, as uv supports both “project” and “script” workflows.

uv add <package>:
- Used for managing a project.
- Updates pyproject.toml and uv.lock.
- Ensures reproducible builds for your application.
- Similar to poetry add.
uv pip install <package>:
- Used for low-level environment modification.
- Does NOT update pyproject.toml.
- Useful for CI/CD pipelines or ad-hoc environments where you just need packages installed quickly without tracking them.
- Similar to pip install.

Caveats

While uv is fantastic, it is moving very fast.

It is relatively new, so edge cases with obscure build backends might still exist.
If you rely heavily on Poetry plugins, uv might not have an equivalent yet.

Conclusion

Give it a try on your next project. You won’t want to go back. At least I won’t. Cheers!

Python init.py Explained: Mastering Package Structure and Imports

Yoonsoo Park — Mon, 09 Feb 2026 00:00:00 +0000

If you’ve ever dug into a popular Python library like requests or pandas, you’ve likely stumbled upon a file named __init__.py. Sometimes it’s empty, sometimes it’s packed with imports, but it’s almost always there.

When I first started with Python, I treated __init__.py as a magical ritual—a file I had to create to make my imports work, without really understanding why.

Turns out, __init__.py isn’t just boilerplate. It’s the gateway to your package. It allows you to transform a messy directory of scripts into a easy-to-use library.

Let’s look at a scenario to see how we can use __init__.py to refactor a messy project into something more professional that you love to show off.

Scenario: Building a Notification System

Imagine you’re building a backend service that needs to send notifications via different channels: Email, SMS, and Push Notifications.

A typical beginner’s project structure might look like this:

1
2
3
4
5
6


notifications/
 __init__.py
 email_service.py
 sms_service.py
 push_service.py
main.py

Inside email_service.py, you might have:

1
2
3
4


# notifications/email_service.py
class EmailSender:
 def send(self, message):
 print(f"Sending Email: {message}")

And similarly for SMS and Push.

The Problem: Clunky, “Deep” Imports

Now, when you want to use these classes in your main.py, you must know exactly which file contains which class. Your imports become long and expose internal file structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# main.py (Without proper __init__.py usage)

from notifications.email_service import EmailSender
from notifications.sms_service import SmsSender
from notifications.push_service import PushSender

def notify_user(msg):
 # Usage is fine, but the imports are ugly
 sender = EmailSender()
 sender.send(msg)

I mean it is okay, but it’s annoying.

Verbose: You have to type notifications.filename every time.
Brittle: If you rename email_service.py to email.py later, you break every file that imports it.

The Solution: Expose Classes in `init.py`

We can use __init__.py to create a shortcut.

Let’s modify notifications/__init__.py to import the classes inside the package, so they are available at the top level.

1
2
3
4
5
6
7
8
9


# notifications/__init__.py

# Use relative import (.) to import from the current directory
from .email_service import EmailSender
from .sms_service import SmsSender
from .push_service import PushSender

# Optional: Control what gets imported with 'from notifications import *'
__all__ = ['EmailSender', 'SmsSender', 'PushSender']

The Result: Clean, “Flat” Imports

Now, look at how beautiful and intuitive main.py becomes. The user doesn’t need to know about email_service.py or sms_service.py. They just import from notifications.

1
2
3
4
5
6
7
8


# main.py (With proper __init__.py usage)

# CLEAN! No need to know internal file names
from notifications import EmailSender, SmsSender

def notify_user(msg):
 sender = EmailSender()
 sender.send(msg)

Why is this better?

Abstraction: The user of your package doesn’t need to know that EmailSender lives in a file called email_service.py. It just lives in the notifications package.
Refactoring Safety: You can move EmailSender to backend/legacy/email.py later, and as long as you update the import in __init__.py, your users won’t notice a thing. Their code doesn’t break.

Advanced Tip: Lazy Loading

One downside of importing everything in __init__.py is that it loads all modules when you import the package. If PushSender requires a heavy library (like a specific SDK) that takes time to load, it might slow down your app even if you only wanted to send an SMS.

You can get fancy with “Lazy Loading” inside __init__.py if performance is critical using __getattr__, but for 99% of projects, the pattern above is the gold standard.

Conclusion

The __init__.py file is a tool for encapsulation. It lets you hide the messy details of your file structure and present a clean, flat interface to the world.

Next time you create a folder in Python, don’t just leave __init__.py empty. Ask yourself: “How do I want other developers to import my code?”

Cheers!

Why Do Python Experts Use the @property Decorator?

Yoonsoo Park — Mon, 09 Feb 2026 00:00:00 +0000

If you are learning Python, you might have come across the @property decorator. While many decorators can seem complex to beginners, @property is often confusing for the opposite reason: its behavior is so simple—it allows you to declare a function but access it like a variable—that many wonder why it is necessary at all.

I recently watched a video by 임커밋 that highlighted the importance of @property not just as syntax sugar, but as a tool for better architectural control. Inspired by that, I wanted to share my own take on why experienced developers lean on this feature.

Here are the two main reasons to use @property.

1. Dynamic Attributes (Computed Properties)

The most common use case arises when the external “look” of a value should be a simple attribute, but the internal logic requires calculation.

Consider an e-commerce ShoppingCart class. A cart contains a list of items, each with a price. Naturally, you want to know the total price.

The Problem

If you define total as a standard instance variable, you must remember to update it every time an item is added or removed.

1
2
3
4
5
6
7
8


class ShoppingCart:
 def __init__(self):
 self.items = []
 self.total = 0 # Needs manual updates!

 def add_item(self, price):
 self.items.append(price)
 self.total += price # Easy to forget or get wrong in complex logic

If a developer modifies items directly or forgets to update total, the data becomes inconsistent!

The Function Solution

You could write a method like get_total(), but accessing it requires parentheses (e.g., cart.get_total()). This works, but it exposes the implementation detail that total is calculated, rather than just being a property of the cart. and we all know less code is better. no code no bug. lol

The @property Solution

By using @property, you can define total as a method internally so it calculates the value fresh every time it is called, but you access it externally like a static attribute (e.g., cart.total).

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


class ShoppingCart:
 def __init__(self):
 self.items = []

 def add_item(self, price):
 self.items.append(price)

 @property
 def total(self):
 return sum(self.items)

cart = ShoppingCart()
cart.add_item(100)
cart.add_item(50)

print(cart.total) # 150 (Computed on the fly!)

This ensures your data is always consistent—the total can never be out of sync with the items list—without sacrificing attribute-like syntax.

2. Read-Only Protection

The second major reason to use @property is to create “read-only” attributes.

Sometimes you have data that should be visible to the outside world but never modified directly. For example, a User class might have a unique id assigned at creation.

If id were a normal attribute, nothing stops a developer from accidentally overwriting it:

1
2


user = User(id=123)
user.id = 456 # Oops! Data integrity broken.

However, when you define a value using @property without a corresponding setter method, it becomes read-only by default.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17


class User:
 def __init__(self, user_id, username):
 self._user_id = user_id
 self.username = username

 @property
 def user_id(self):
 return self._user_id

user = User(101, "python_guru")
print(user.user_id) # 101

# Attempting to modify it raises an error
try:
 user.user_id = 999
except AttributeError as e:
 print(e) # can't set attribute

This behavior allows developers to protect sensitive or critical data (like IDs, timestamps, or derived values) from being accidentally overwritten by external code. It effectively isolates the internal logic from external interference.

Conclusion

While it might seem like a small syntactic sugar, the @property decorator is a something you need to consider for encapsulation. It allows you to maintain the clean interface of simple attributes while keeping the safety of dynamic functions in the background.

Build a Governed Agent Platform on AWS

Yoonsoo Park — Sat, 20 Dec 2025 00:00:00 +0000

An “agent factory” should not mean giving a model broad IAM permissions and asking it to create roles, repositories, images, and runtimes directly. Natural language can propose an agent, but production infrastructure needs a deterministic, reviewable control plane.

The safer pattern is a governed internal platform: an agent specification becomes a pull request or signed request, policy and evaluation gates produce evidence, and a deployment service—not the agent being built—applies an approved template.

Define the product contract

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


name: order-status-assistant
owner: commerce-platform
protocol: HTTP
model_policy: approved-low-risk
tools:
 - get_order_status
data_classification: internal
memory:
 enabled: false
network:
 internet_egress: false
human_gate:
 required_for_write_tools: true
budgets:
 max_runtime_seconds: 120
 max_tool_calls: 8

Validate this schema and reject unknown fields. Resolve tool names through an approved catalog whose entries include owner, input/output schema, authorization model, data class, availability, and test endpoint. A prompt cannot request an arbitrary role ARN or container image.

Separate planes and identities

The platform control plane validates specs, synthesizes CDK/CloudFormation/Terraform, runs policy checks, builds images, creates an immutable release, and deploys AgentCore resources. Its privileged actions run under a tightly controlled CI/deployment role with approvals and audit.

The agent data plane handles invocations with a per-agent execution role. It cannot create IAM roles, alter its runtime, publish images, or grant itself tools. AgentCore Identity/Gateway may provide outbound credentials and tool access, but each target still authorizes the actual action.

Use separate roles for source checkout, image build, infrastructure deployment, runtime execution, and break-glass recovery. External CI should assume roles through OIDC. Never use aws configure or a developer’s static key in automation.

Supply-chain controls

Build from a pinned base image and lock dependencies. Generate an SBOM, scan dependencies and image, sign the image, store it in private ECR with immutable tags, and deploy by digest. Record source commit, build identity, evaluation result, policy version, image digest, model configuration, and infrastructure plan in release provenance.

Templates should provide secure defaults: log redaction, encryption, private networking where needed, bounded egress, resource tags, deletion/retention, lifecycle settings, alarms, and budgets. Exceptions require an owner, rationale, expiry, and additional test.

Evaluation gates

Run deterministic application tests before model evaluation. Then test representative and adversarial cases for task success, tool argument validity, authorization, prompt injection, unsafe actions, data leakage, refusal/escalation, latency, and cost. Compare against a simple baseline; do not approve a multi-agent topology if it adds expense without improving outcomes.

Write tools need sandbox or draft-mode tests and idempotency. Cross-tenant systems require negative isolation tests. Browser or code execution requires network and artifact controls. A human reviewer approves risk-sensitive releases with the evidence attached, not a generated summary alone.

Deployment and operations

Promote the same immutable artifact from development to staging and production with environment-specific configuration. Start with shadow/read-only traffic, then a small canary. Monitor task success, human correction, tool denials, runtime errors, latency, token/tool cost, queue/backlog if applicable, and anomalous identity use.

Rollback switches traffic to the previous compatible artifact and configuration. Memory/schema/tool-contract changes need forward/backward compatibility or an explicit migration restore plan. Provide a kill switch that revokes invocation or tool authority independently of a full deployment.

Tradeoffs

A platform accelerates many teams and centralizes controls, but it can become a bottleneck or lowest-common-denominator abstraction. Start with two or three repeated agent patterns, not a universal factory. Direct team-owned deployment may be better for an early experiment; require the same identity, test, and cost boundaries before granting production authority.

Migration checklist

Remove infrastructure mutation permission from builder agents.
Convert desired behavior to a versioned, validated spec.
Create approved runtime and tool templates with narrow roles.
Build/sign/scan immutable artifacts in CI and review the infrastructure plan.
Add deterministic, model, security, isolation, cost, and recovery gates.
Separate release approval from runtime identity.
Add canary, provenance, alarms, budgets, kill switch, and rollback.
Pilot one low-risk agent and measure platform lead time and escaped defects.

Verified on 2026-08-01.

Primary sources

Zero-Trust Agent Systems on AWS

Yoonsoo Park — Wed, 17 Dec 2025 00:00:00 +0000

An agent calling another agent is a distributed-system request, not an implicit continuation of user trust. Each hop needs an authenticated workload, an explicit representation of user delegation where required, authorization at the resource, and an auditable decision.

This is especially important in finance, healthcare, and other consequential systems, but compliance labels do not determine the architecture by themselves. Build from the actual data, action, threat, and regulatory requirements.

Separate the identities

There are at least three principals:

the end user requesting an outcome;
the agent workload executing code;
the target tool/service enforcing access.

AgentCore Runtime supports IAM SigV4 inbound authentication or configured JWT authorization. Those are modes, not two headers that every call automatically combines. AgentCore Identity workload identities can broker outbound credentials. If downstream authorization needs the user’s authority, propagate a verifiable, audience-restricted delegation token or a trusted user identifier through a documented flow. Never trust tenantId: Alice inside model-generated JSON.

At every tool call, authorize the workload and, where applicable, the delegated user against the specific action and resource. Keep the target service’s authorization even when Gateway or an interceptor performs an earlier policy check. This is defense in depth and prevents a routing mistake from becoming a data breach.

Minimize authority

Expose get_account_balance(account_id) rather than database credentials or arbitrary SQL. Validate that the account belongs to the authorized subject. Use separate read and write tools, transaction limits, idempotency keys, and human approval for irreversible or regulated actions. A supervisor agent should not pass its broader execution role to a specialist.

Use per-component IAM roles and constrain trust policies. Protect OAuth/API-key credentials in AgentCore Identity or an approved secret system; never place them in prompts or memory. Rotate and revoke credentials independently of model deployment.

Network boundaries

AWS PrivateLink interface endpoints provide private connectivity from a VPC to supported AgentCore service APIs. VPC configuration can also let Runtime and tools reach private resources, with VPC Lattice used for supported connectivity patterns. This does not mean AgentCore’s managed control plane and every component “run inside your VPC.” Document inbound endpoint traffic, Runtime/tool egress, DNS, security groups, NAT, and third-party destinations separately.

A private path does not authorize a request. Keep TLS, IAM/JWT checks, application authorization, and data-level controls. Browser tools that need the public internet require an approved egress path and stronger content isolation.

Memory and data

Scope AgentCore Memory by actor and session and design long-term namespaces, but enforce tenant access in application/IAM policy as supported. Classify what may enter prompts, traces, raw events, extracted memories, and tool logs. Define retention, deletion, legal hold, encryption keys, residency, and redaction. Test that one tenant cannot retrieve another tenant’s records even with guessed identifiers.

Threats and evaluation

Include prompt injection, confused deputy, excessive agency, token replay, cross-tenant identifiers, malicious tool output, data exfiltration, duplicate financial action, unavailable policy service, and compromised agent in the threat model.

Negative tests should prove:

invalid/expired/audience-mismatched tokens fail;
an allowed workload cannot exceed the delegated user’s scope;
read-only agents cannot reach write tools;
repeated requests produce one business effect;
interceptor/policy failure closes access;
private endpoints do not create unintended public egress;
logs and traces contain no secrets or prohibited financial data.

Rollout and response

Start read-only with synthetic data, then draft actions, then human-approved low-value actions. Define per-user and per-agent budgets, rate limits, anomaly alarms, and a kill switch that disables tool authority without waiting for a model redeploy. Preserve immutable audit records linking user, workload, policy decision, tool, request ID, and result.

Migration checklist

Replace “automatic identity propagation” assumptions with a sequence diagram of real tokens and validators.
Select SigV4 or JWT inbound auth per caller and document outbound credential exchange.
Add target-side authorization and narrow tools.
Map PrivateLink inbound, VPC egress, Lattice, NAT, and public dependencies accurately.
Add cross-tenant, replay, idempotency, and fail-closed tests.
Define retention, incident revocation, rollback, and human approval.

Verified on 2026-08-01.

Primary sources

Validate Policy Claims with Amazon Bedrock Automated Reasoning Checks

Yoonsoo Park — Tue, 16 Dec 2025 00:00:00 +0000

Amazon Bedrock Automated Reasoning checks can validate whether translated claims logically follow from a formalized policy. The solver is deterministic for the formal problem it receives. The overall system is not: natural-language policy translation can be incomplete or ambiguous, input may be out of scope, and a valid claim can still be unsafe for reasons the policy does not encode.

Use Automated Reasoning as one policy-verification layer, not as universal authorization or a guarantee that an answer is true.

Build and version the policy

Create a focused policy from authoritative source documents. Review extracted variables, types, and rules with domain owners. Test contradictory, boundary, missing-information, and out-of-domain examples. Keep unrelated domains in separate policies.

The working DRAFT changes during development. Publish an immutable numbered policy and guardrail version for production so an edit cannot silently change deployed behavior. Record source-document version, reviewer, tests, and release date.

Validate with `ApplyGuardrail`

ApplyGuardrail is the recommended standalone API when the application controls generation and validation separately. Provide at least one claim block. Include the user query as context when the policy decision depends on stated conditions.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


import boto3

client = boto3.client("bedrock-runtime", region_name="us-east-1")
response = client.apply_guardrail(
 guardrailIdentifier="guardrail-id",
 guardrailVersion="3",
 source="OUTPUT",
 content=[
 {"text": {"text": "User: I bought it 45 days ago.", "qualifiers": ["query"]}},
 {"text": {"text": "Assistant: You qualify for a refund.", "qualifiers": ["guard_content"]}},
 ],
)

Do not only check response["action"]. Inspect assessments[].automatedReasoningPolicy.findings. A finding can be valid, invalid, satisfiable, impossible, translation-ambiguous, too complex, or have no translations. Only invalid directly establishes contradiction under the translated policy. Ambiguous or missing translations should trigger clarification, safe fallback, or human review—not approval.

Use a numbered version in production, not DRAFT. Confirm Automated Reasoning actually ran by monitoring assessment and usage data; a mis-tagged Converse request can succeed without performing the intended check.

Enforcement flow

Authenticate and authorize the user’s requested action in application code.
Retrieve the applicable versioned policy and required factual inputs from trusted systems.
Generate or receive a proposed claim/action.
Run Automated Reasoning and interpret all findings.
Block invalid results; clarify satisfiable/ambiguous cases; escalate complex/no-translation cases.
Re-check mutable business data immediately before execution.
Record policy version, non-sensitive inputs, findings, decision, actor, and request ID.

Guardrails do not grant refunds, approve loans, or authorize records. The transactional service must enforce identity, permissions, limits, state, idempotency, and audit.

Other guardrail layers

Denied topics, content and word filters, sensitive-information filters, and contextual grounding checks solve different problems. Apply the smallest relevant set and understand qualifiers. Contextual grounding evaluates support/relevance against supplied source and query; it is not the same as formal policy entailment.

Evaluation and operations

Maintain golden policy cases, adversarial paraphrases, omitted facts, conflicting premises, out-of-domain requests, multilingual inputs, and policy-version regression tests. Measure false allow, false block, ambiguous/no-translation rate, latency, cost, and human escalation. Sample production decisions under privacy controls and provide a kill switch or conservative fallback.

Migration checklist

Replace deterministic-safety claims with a bounded policy-check description.
Review the translated formal policy with domain experts.
Publish and pin numbered versions.
Inspect findings, not only intervention action.
Add explicit handling for every finding type.
Keep authorization and transaction controls outside the model/guardrail.
Add regression evaluation, monitoring, audit, and rollback to the prior policy version.

Verified on 2026-08-01.

Primary sources

Amazon Bedrock AgentCore: A Service Map for Production Boundaries

Yoonsoo Park — Mon, 15 Dec 2025 00:00:00 +0000

Amazon Bedrock AgentCore is a collection of managed capabilities, not an “infrastructure-as-code layer” that automatically makes an agent production-ready. Each service solves a different boundary, exposes separate control- and data-plane APIs, and still requires application authorization, evaluation, cost controls, and recovery design.

Runtime

AgentCore Runtime hosts an agent application in an isolated runtime session. It supports HTTP, MCP, and A2A protocol contracts with different required ports and paths. An invocation uses either IAM SigV4 or configured JWT authorization. Runtime lifecycle settings control idle timeout and instance maximum lifetime; durable business state must live outside the runtime.

Package a stateless application, pin dependencies and image digest, give its execution role only required AWS actions, and test the exact protocol contract. Do not assume a base image or SDK helper from a conference example remains current.

Identity

AgentCore Identity manages workload identities and credential providers for outbound access. It can broker OAuth 2.0 or API-key credentials without embedding them in prompts or source code. Inbound runtime authentication and outbound tool authorization are different decisions. A valid user JWT does not automatically authorize a tool action, and user context propagation must be designed explicitly.

Gateway

Gateway exposes Lambda functions, APIs, and other targets as MCP-compatible tools. Define narrow schemas, validate at the target, and authorize against the authenticated actor. Request/response interceptors can run Lambda code for transformation or custom policy, but they have limits, retries, latency, and sensitive-header handling requirements. Gateway is not a substitute for the target system’s own authorization.

Memory

Memory stores short-term events under actor/session identifiers and can asynchronously extract long-term records with configured strategies and namespace templates. Applications call event and retrieval APIs; they decide what data is appropriate to store and inject. Namespace organization helps isolation but does not replace IAM and tenant authorization. Set retention, KMS, deletion, consent, and evaluation for extracted memories.

Browser and Code Interpreter

These tools provide managed execution environments for browsing and code. They reduce infrastructure work, not risk. Browser content is untrusted and can contain prompt injection. Code execution needs input/output limits, network policy, artifact scanning, time budgets, and a decision about which generated files can leave the sandbox.

Observability

Use traces, logs, and metrics to connect model calls, tool decisions, gateway targets, memory operations, and user-visible outcomes. Redact prompts, tokens, credentials, and sensitive tool payloads. Track task success, unsafe-action rate, human escalation, latency, token/tool cost, retries, and recovery—not only model token counts.

A production selection process

Start with the application and threat model; select only services that solve a stated requirement.
Draw identities and authorization at every hop.
Define durable state, idempotency, timeout, retry, compensation, and human gates.
Pin protocol, SDK, image, and model versions where supported.
Build negative tests for denied tools, cross-user memory, malicious content, unavailable dependencies, and budget exhaustion.
Deploy a read-only or draft-producing pilot, compare against a simpler baseline, then expand authority gradually.

AgentCore can reduce undifferentiated hosting and integration work, but it introduces AWS-specific services, quotas, Regions, IAM policy, and variable cost. A self-hosted runtime or ordinary service may be simpler for a narrow agent. A workflow engine is usually better for deterministic, durable business orchestration.

Before adoption, estimate steady and burst traffic, session lifetime, tool calls, memory extraction, observability volume, and idle resources. Confirm quotas and pricing in the chosen Region, then set budget alarms and load-test the failure limits.

Migration checklist

Remove illustrative APIs that are not present in current SDK documentation.
Separate control-plane provisioning from data-plane invocation.
Replace broad roles with per-component least privilege.
Move secrets to Identity/Secrets Manager and durable state to explicit stores.
Add retention/deletion policy for memory and logs.
Establish service quotas, cost alarms, evaluation gates, and rollback.
Verify each capability in the intended Region and account before claiming production support.

Verified on 2026-08-01.

Primary sources

Real-Time Voice Agents with Amazon Nova 2 Sonic

Yoonsoo Park — Sun, 14 Dec 2025 00:00:00 +0000

A good voice agent is not simply a text agent with speech recognition and synthesis attached. Users speak over it, change their minds while a tool runs, pause unpredictably, and expect private audio to disappear when the conversation ends. Amazon Nova 2 Sonic handles speech-to-speech interaction through Amazon Bedrock’s bidirectional streaming API, but the application still owns transport, playback, tools, identity, and consent.

Put a trusted relay between browser and Bedrock

Do not place AWS credentials in a browser or mobile client. Capture microphone frames on the client and send them over a protected WebSocket or WebRTC connection to an authenticated backend. The backend uses SigV4 credentials to open InvokeModelWithBidirectionalStream and relays structured events.

flowchart LR
Mic[Microphone] --> Client[Client audio queue]
Client -->|authenticated stream| Relay[Application relay]
Relay -->|SigV4 bidirectional API| Nova[Nova 2 Sonic]
Nova --> Relay
Relay -->|audio and events| Client
Relay --> Tools[Authorized tools]

Use the model ID documented for the deployment Region, currently amazon.nova-2-sonic-v1:0 in the AWS getting-started example. Model availability changes, so keep it in validated configuration rather than hard-coding it across clients.

The API is event-driven. Start a session, start a prompt, then frame each piece of system, user, assistant, tool, or system-speech content with contentStart, its content event, and contentEnd. Maintain prompt, content, completion, session, and tool-use identifiers exactly as the protocol returns them. Use the official full-featured sample as the starting point; the basic sample intentionally omits true bidirectional behavior and barge-in.

Make interruption a client state transition

When the user interrupts, Nova 2 Sonic stops generating speech and emits an interruption notification. The client must immediately stop the audio device and discard queued assistant audio associated with the interrupted completion. Merely stopping the network stream leaves buffered speech playing, which makes the agent appear to ignore the user.

Keep playback data keyed by completion ID. On interruption, invalidate that ID; reject late chunks from it; keep capturing microphone audio; and update the UI from “speaking” to “listening.” Test with headphones and speakers, because echo cancellation, device latency, and browser scheduling change behavior.

Asynchronous tools need application control

Nova 2 Sonic can continue listening and responding while tools execute. A changed request does not automatically cancel an earlier tool, and the result is still delivered to the model. Therefore tool execution needs explicit lifecycle state.

1
2
3
4
5
6
7
8
9


async def execute_tool(call, context):
 args = validate_schema(call.tool_name, call.content)
 authorize(context.principal, call.tool_name, args)
 result = await tools.run(
 call.tool_name, args,
 idempotency_key=call.tool_use_id,
 timeout_seconds=8,
 )
 return redact_and_bound(result)

The model’s tool selection is not authorization. Validate schemas, enforce tenant and resource ownership outside the model, set timeouts and size limits, and require confirmation for consequential actions. If an obsolete tool result returns after the user changes intent, mark its generation or request version so the application can prevent stale writes even though the result is delivered to the conversation.

For RAG, wrap retrieval as a read-only tool and return a small set of cited passages. Do not give retrieved text authority over system instructions. For complex workflows, call a durable service rather than hiding a long-running agent behind a voice tool timeout.

Privacy and safety are product behavior

Ask for microphone permission in context and visibly show recording state. Offer mute and immediate end controls. Decide whether audio, transcripts, tool inputs, and synthesized responses are stored; default to the least retention compatible with the product. Redact sensitive values before general logging, encrypt retained artifacts, and document deletion.

Tell users they are speaking to AI. For regulated or high-impact actions, repeat the interpreted request and obtain confirmation. Provide a human handoff when confidence is low or the user asks for one. Evaluate accents, speech impairments, background noise, languages, and unsafe-content behavior with representative participants.

Connection renewal and measurement

AWS documents an eight-minute connection limit and provides a renewal/continuation pattern. Renew before the deadline, preserve only the approved conversation context, and make reconnect visible when continuity cannot be guaranteed.

Measure microphone-to-first-audio latency, interruption-to-silence latency, turn-end detection errors, reconnect success, tool latency, task success, and user corrections. Log event timings and identifiers without storing raw audio by default. Load-test concurrent streams and enforce per-user quotas so one client cannot exhaust streaming capacity.

Migration checklist

Move from Nova Sonic v1 examples to the Nova 2 documentation and model configuration. Replace ad hoc WebSocket-to-model assumptions with the supported bidirectional event sequence. Adopt the full-featured sample, implement completion-aware buffer clearing, add asynchronous tool state and authorization, then run privacy and interruption acceptance tests on real devices before rollout.

References

Reviewed against official documentation on 2026-08-01.

Multi-Tenant Isolation with Amazon Bedrock AgentCore

Yoonsoo Park — Sat, 13 Dec 2025 00:00:00 +0000

Multi-tenant agents add a dangerous ambiguity: the model can talk about a tenant, but only trusted application code can establish which tenant the caller belongs to. Amazon Bedrock AgentCore provides useful isolation primitives, yet none replaces an end-to-end tenant authorization design.

Start by separating four identities: the authenticated human or workload, the tenant, the AgentCore runtime session, and the AWS execution role. They may be related, but they are not interchangeable. In particular, a runtime session ID isolates runtime state; it is not proof of tenant membership.

Establish tenant context before the model

Authenticate at the edge. Resolve tenant membership from a trusted directory or entitlement service. Construct server-side request context and reject any tenant identifier supplied only by the prompt or browser.

1
2
3
4
5
6


{
 "principalId": "user-7c91",
 "tenantId": "tenant-42",
 "roles": ["case-reader"],
 "requestId": "req-a813"
}

Sign or integrity-protect this context between services and validate audience, issuer, expiry, and tenant membership at every trust boundary. Do not ask the model whether a request is allowed. The model can help interpret intent; a deterministic policy layer must authorize the resulting operation.

Choose the isolation tier deliberately

A pooled runtime is efficient, while dedicated resources reduce blast radius. Use pooled compute with strong logical controls for lower-risk workloads. Consider separate runtime, memory, KMS key, network path, or AWS account for regulated data or tenants requiring hard isolation. Document which components are pooled and which are siloed.

AgentCore Runtime creates isolated session execution environments. Still, never cache tenant data in process-global variables, reuse temporary files across sessions, or derive a tenant from previous conversation content. Keep each invocation and tool request bound to validated server context.

Make memory isolation enforceable

AgentCore Memory events are organized by actorId and sessionId; long-term records use configured namespaces. Use opaque actor IDs mapped server-side to tenant and user. A useful namespace includes the strategy and trusted tenant/actor scope, for example:

1

/tenant/tenant-42/strategy/{memoryStrategyId}/actor/user-7c91/

Organization alone is not access control. Restrict the specific memory ARN and permitted namespace with documented IAM condition keys such as bedrock-agentcore:namespace and bedrock-agentcore:namespacePath. If one shared execution role can calculate any tenant path, IAM alone may not prevent confused-deputy bugs; add a policy decision point or assume tenant-scoped roles with session tags from a trusted broker.

Avoid placing raw tenant IDs in logs or URLs when opaque identifiers work. Define deletion, export, and retention by tenant and actor before enabling long-term strategies.

Authorize every tool and data query

An MCP or A2A boundary does not make a tool tenant-aware. Pass trusted context out of band from model arguments. At the tool service, derive the permitted tenant and add it to every storage query. Prefer database row-level security or partition keys plus authorization over a prompt instruction such as “only access this tenant.”

For writes, validate resource ownership, action, amount, and state. Use idempotency keys and require step-up approval for consequential actions. Downstream credentials should be short-lived and least-privileged. Do not forward the caller’s bearer token to an arbitrary agent selected from an Agent Card.

Observe without leaking

Include request, tenant, actor, session, tool, policy decision, and trace identifiers in structured audit records, but keep prompts and tool payloads out of general logs by default. Encrypt tenant artifacts, use tenant-aware metric dimensions only where cardinality and privacy allow, and alert on cross-tenant denials. Log policy inputs and outcomes so an investigation does not depend on model prose.

Migration and isolation testing

Before pooling an existing single-tenant agent, inventory every state location: runtime memory, AgentCore Memory, caches, object prefixes, vector indexes, database rows, queues, traces, and analytics exports. Add tenant keys and authorization first, backfill data with reconciliation, then enable pooled traffic gradually.

Build a two-tenant adversarial suite. Reuse session IDs, swap actor IDs, forge context, request another tenant’s object through a tool, inject identifiers through retrieved documents, retry old requests, and inspect logs and caches. Test both allowed and denied cases. Run canaries that place unique markers in each tenant and continuously verify that search, memory retrieval, tools, exports, and deletion never cross the boundary.

References

Reviewed against official documentation on 2026-08-01.

Designing Multi-Agent Systems Only When One Agent Is Not Enough

Yoonsoo Park — Fri, 12 Dec 2025 00:00:00 +0000

Multiple agents add coordination; they do not automatically add intelligence. Begin with one agent and a small typed tool set. Add another agent only when an explicit boundary—context, skill evaluation, security, ownership, or parallelism—improves a measured outcome.

Four useful structures

Single agent with tools

This is the baseline. One policy, one context owner, and one trace make failures easier to understand. It often beats a multi-agent design for short tasks and shared context.

Supervisor and specialists

A supervisor decomposes work and delegates to specialists with narrow contracts. It is useful when specialists need distinct context or tools. The supervisor should receive structured results and evidence, not every raw page or tool trace. “Context hiding” is not deleting relevant facts; it is deliberate summarization with source references and uncertainty.

Failure modes include a weak decomposition, repeated delegation, lossy summaries, and a supervisor accepting an invalid result. Set delegation depth, time/token/tool budgets, schemas, and a fallback to human review.

Peer-to-peer A2A

Peer agents expose capabilities and communicate through a protocol such as A2A. This fits independently owned services, but discovery, authentication, authorization, version compatibility, deadlines, and audit are platform responsibilities. Do not let a caller’s text claim establish user identity.

Deterministic workflow or DAG

When dependencies and transitions are known, a workflow engine should own them. It provides durable state, retries, timeouts, compensation, and approval. Model steps can classify, draft, or recommend within nodes. This is usually more reliable than asking an LLM to remember the workflow.

ReWOO and plan-then-execute techniques can reduce repeated observation and model calls, but a precomputed plan can become stale. Add checkpoints that revalidate assumptions before consequential actions.

Contract for every delegation

Define objective, allowed inputs, tool authority, output schema, evidence, deadline, idempotency key, and failure behavior. A specialist should return status, result, sources, uncertainty, and safe retry information. Treat its output as untrusted at the next boundary.

Propagate authenticated identity separately from model content. Re-authorize tool calls at the target. Give specialists only their needed tools, and keep write operations behind human or policy gates.

Evaluate the system, not the conversation

Create a single-agent baseline and compare:

end-to-end task success and factual grounding;
incorrect delegation and invalid handoff rate;
unauthorized or unnecessary tool attempts;
latency, token/tool cost, and retry amplification;
recovery from timeout, duplicate message, partial result, and unavailable specialist;
reviewer correction and escalation quality.

Run adversarial tests with prompt injection in retrieved content and agent messages. Test cyclic delegation, conflicting specialists, stale memory, budget exhaustion, and one agent returning a syntactically valid but false result.

Operational pattern

Store durable task state outside prompts. Use correlation IDs and traces across hops, redact sensitive content, and record model/tool/config versions. Cap concurrency to protect downstream services. Make actions idempotent. Provide cancellation and a kill switch. A session that times out must be resumable from durable state or fail explicitly.

Migration checklist

Measure the current single-agent baseline.
Identify the precise boundary each proposed agent owns.
Replace free-form handoffs with versioned schemas and evidence.
Put known sequencing in a workflow engine.
Add hop-by-hop identity and authorization.
Set delegation, time, cost, and tool budgets.
Add fault injection and security evaluation.
Remove agents that do not improve success enough to justify complexity.

Verified against the A2A specification, MCP specification, and AWS Step Functions guidance on 2026-08-01.

MCP and A2A Boundaries on Amazon Bedrock AgentCore

Yoonsoo Park — Thu, 11 Dec 2025 00:00:00 +0000

Model Context Protocol (MCP) and Agent-to-Agent (A2A) are not “hands” and “voices” that every agent must have. They are different wire contracts. MCP exposes tools and contextual resources to a model-facing client. A2A exposes an agent, its capabilities, and task-oriented interaction to another application or agent. Sometimes plain HTTP is the smaller and better boundary.

Amazon Bedrock AgentCore Runtime supports all three. The choice affects the port, mount path, message format, discovery mechanism, and client expectations.

Contract	Runtime endpoint	Discovery	Good fit
HTTP	port 8080, `/invocations` or `/ws`	application-defined	direct application calls and streaming
MCP	port 8000, `/mcp`	tool listing	bounded tools or an MCP server
A2A	port 9000, `/`	Agent Card	interoperable agent delegation

Do not run several contracts behind one runtime and infer the requested protocol from payload shape. Deploy and test each public contract independently.

Use MCP for constrained capabilities

An MCP tool should have a narrow name, JSON schema, predictable errors, and an authorization check at execution time. The model choosing a tool is not approval. Validate arguments, bind the caller to permitted resources, rate-limit costly operations, and require confirmation for consequential writes.

MCP is useful when multiple compatible clients need the same tools. A normal internal function is preferable when there is only one process and no interoperability requirement. Adding a network protocol creates authentication, versioning, observability, and availability work.

Treat tool descriptions and returned text as untrusted content. A document fetched through MCP can contain instructions aimed at the model. Keep system policy separate, label provenance, sanitize output used in another command, and never turn retrieved text directly into shell or database operations.

Use A2A for an agent-shaped service

AgentCore’s A2A contract uses JSON-RPC 2.0 over HTTP and serves the Agent Card at /.well-known/agent-card.json. The Agent Card is metadata for discovery; it is not a search engine, trust proof, or authorization grant. Production routing should use an allow-listed registry and verify the destination’s identity and advertised capabilities.

The current AgentCore and Strands integration wraps a Strands agent with the supported executor and runtime helper:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


from strands import Agent, tool
from strands.multiagent.a2a.executor import StrandsA2AExecutor
from bedrock_agentcore.runtime import serve_a2a

@tool
def summarize_case(case_id: str) -> str:
 """Return an authorized case summary for the current caller."""
 return load_authorized_summary(case_id)

agent = Agent(tools=[summarize_case])

if __name__ == "__main__":
 serve_a2a(StrandsA2AExecutor(agent))

This establishes protocol compatibility; it does not implement business authorization. AgentCore can authenticate invocation with SigV4 or OAuth 2.0. The service must still decide whether that principal may read the requested case and invoke downstream tools. Do not forward a user token indiscriminately. Prefer token exchange or service credentials with explicit, least-privilege delegation, and record the initiating principal separately from the workload identity.

Propagate context deliberately

AgentCore adds a runtime session header for session isolation. Session identity is not tenant identity. Carry correlation, tenant, and end-user context in a signed or server-established envelope, validate it at every hop, and avoid trusting values generated by the model.

For A2A, define timeouts and cancellation, bound task fan-out, and preserve a trace ID across calls. A delegation graph can otherwise loop or multiply costs. Return structured errors and avoid embedding secrets or raw internal stack traces in JSON-RPC error data.

Migration and evaluation

Start with an inventory of existing tools and agent endpoints. Keep deterministic, narrow operations as functions or MCP tools. Expose A2A only where independent ownership, capability discovery, or cross-framework delegation provides real value. Put legacy adapters behind the new boundary and migrate clients gradually instead of changing orchestration and protocol simultaneously.

Contract-test Agent Card retrieval, JSON-RPC errors, authentication failures, tool schemas, cancellation, and streaming. Security tests should include forged tenant context, prompt injection in tool output, a compromised downstream agent, excessive delegation, and replayed requests. Compare task success, latency, token use, tool error rate, and authorization denials before and after migration.

References

Reviewed against official documentation on 2026-08-01.

AgentCore Memory Events, Strategies, and Isolation

Yoonsoo Park — Tue, 09 Dec 2025 00:00:00 +0000

Agent memory is not one database that magically remembers a user. Amazon Bedrock AgentCore Memory has a concrete model: a memory resource stores immutable short-term events, while configured strategies asynchronously derive long-term memory records. Applications must choose actor and session identifiers, namespace layouts, retention, retrieval rules, and authorization.

The current data model

An event is a timestamped interaction associated with a memoryId, actorId, and sessionId. A conversation turn, tool result, or application activity can become an event. Short-term retrieval follows the actor and session. If the memory resource has strategies, those strategies process events into records for long-term retrieval.

Built-in strategies cover common needs such as semantic facts, summaries, user preferences, and episodic information. A self-managed strategy is appropriate when extraction must be deterministic, independently audited, or driven by domain logic. It lets an application extract records itself and use batch record APIs instead of inventing a nonexistent “save insight” hook.

flowchart LR
App[Application] -->|CreateEvent| Events[(Events)]
Events --> Strategy[Managed or custom strategy]
Strategy -->|asynchronous| Records[(Memory records)]
App -->|ListEvents| Events
App -->|RetrieveMemoryRecords| Records

The write path and long-term read path have different consistency expectations. A newly created event can be read as short-term history, but derived records may not exist immediately. Design the prompt assembly path to tolerate that delay.

Write events through the supported API

The SDK helper below follows the documented session model and keeps actor and session explicit:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


from bedrock_agentcore.memory import MemorySessionManager
from bedrock_agentcore.memory.constants import ConversationalMessage, MessageRole

manager = MemorySessionManager(memory_id=MEMORY_ID, region_name="us-west-2")
session = manager.create_memory_session(
 actor_id=stable_actor_id,
 session_id=conversation_id,
)
session.add_turns(messages=[
 ConversationalMessage("I prefer email updates.", MessageRole.USER),
 ConversationalMessage("I'll use email for updates.", MessageRole.ASSISTANT),
])

Generate stable_actor_id in the trusted application tier after authentication. Do not accept an arbitrary actor ID from a browser and forward it unchanged. Session IDs should be unique, opaque, and bound to the authenticated actor in application state.

Never place passwords, access tokens, payment data, or unnecessary personal data in events. Extraction can copy sensitive input into a durable record. Apply redaction before writing, define an event expiry duration, and implement deletion and subject-access workflows appropriate to the data.

Namespace design is part of the contract

Namespaces organize records produced by each strategy. Use documented template variables rather than string concatenation inside prompts. A typical actor-scoped shape is:

1

/strategy/{memoryStrategyId}/actor/{actorId}/

Include {sessionId} only when memories should not carry across sessions. A global namespace makes sense only for intentionally shared, non-user-specific knowledge. Changing the namespace later creates a migration problem because old and new records live under different paths; version a namespace when its meaning changes.

Namespace organization is not sufficient authorization. Enforce retrieval with IAM condition keys such as bedrock-agentcore:namespace or bedrock-agentcore:namespacePath, and constrain the memory resource ARN. The principal used by the application still needs a trusted mapping from identity to permitted namespace.

Retrieval and prompt assembly

Retrieve only the strategies and namespace needed for the current task. Apply a small result limit, filter by relevance, label memory as untrusted context, and avoid letting recalled text override system policy. When the system must know a fact—an account balance, entitlement, or approval—read the authoritative service instead of memory.

Store provenance with application records: actor, session, event ID, strategy, namespace, creation time, and the prompt or extraction version where available. These fields make it possible to explain why a memory appeared and to remove bad records.

Migration and evaluation

Replace custom hooks with CreateEvent or the SDK session helper. Map old users to stable actors and old conversations to sessions. Choose strategies and namespaces before importing anything; use self-managed batch operations for vetted legacy facts. Run imports with checkpoints and keep a reconciliation report.

Evaluate more than recall quality. Test cross-actor and cross-tenant denial, delayed extraction, deletion, poisoned instructions inside remembered text, contradictory updates, empty retrieval, and strategy changes. Measure whether relevant memories help task success without leaking information or displacing authoritative data.

References

Reviewed against official documentation on 2026-08-01.

Durable Long-Running Jobs with Amazon Bedrock AgentCore

Yoonsoo Park — Mon, 08 Dec 2025 00:00:00 +0000

Amazon Bedrock AgentCore Runtime can run asynchronous work for up to eight hours. That is useful, but it is not the same as durable execution. A fraud investigation that waits two days for a document, or an onboarding flow paused for manager approval, cannot depend on one runtime session staying alive.

The useful boundary is simple: AgentCore Runtime performs bounded agent work; a durable orchestrator owns the business process.

Separate runtime state from workflow state

Treat a runtime invocation as replaceable. Give it an idempotent unit of work, persist results outside the runtime, and let AWS Step Functions or another durable workflow engine decide what happens next.

flowchart LR
API[Request] --> SFN[Step Functions]
SFN --> Q[SQS work item]
Q --> AC[AgentCore Runtime]
AC --> S3[(S3 artifact)]
AC --> DDB[(DynamoDB checkpoint)]
DDB --> SFN
SFN -->|approval token| Human[Reviewer]

Use AgentCore Memory for conversational continuity, preferences, and extracted knowledge. Do not use it as the source of truth for job status, approvals, money movement, or exactly-once processing. Those belong in a transactional store with explicit state transitions.

Define a restart-safe work contract

Every work item should carry a stable job ID, step ID, attempt number, input reference, and output location. Avoid putting large or sensitive payloads directly on a queue.

1
2
3
4
5
6
7


{
 "jobId": "case-8f2c",
 "stepId": "summarize-evidence",
 "attempt": 2,
 "input": "s3://private-case-data/case-8f2c/manifest.json",
 "output": "s3://private-case-data/case-8f2c/summary.json"
}

Before doing expensive work, conditionally claim the step in DynamoDB. Write the result to a versioned object, then conditionally mark the step complete. A retry should return the existing result instead of repeating an external action. For side-effecting tools, pass an idempotency key through to the downstream API when it supports one.

The agent should emit structured progress rather than relying on an open HTTP response:

1
2
3
4
5
6
7
8
9


def handle_step(item, jobs, artifacts):
 key = {"job_id": item["jobId"], "step_id": item["stepId"]}
 if jobs.is_complete(key):
 return jobs.result(key)
 lease = jobs.claim(key, attempt=item["attempt"])
 result = run_bounded_agent_task(item["input"])
 uri = artifacts.put_json(item["output"], result)
 jobs.complete(key, lease=lease, result_uri=uri)
 return {"resultUri": uri}

This is application-level pseudocode: the important part is the conditional claim and completion, not a particular library.

Heartbeats are liveness, not durability

AgentCore Runtime supports background tasks and reports status through its runtime contract. Keep the runtime responsive to health checks while background work runs, and stay within the documented execution limit. A heartbeat only says the current process is alive; it does not recreate lost work after termination.

Split work that might approach the limit. For example, process a corpus in batches and checkpoint after each batch. Let the orchestrator start the next invocation. If a task cannot be divided, run it on a compute service whose lifetime matches the task, while using AgentCore only for the reasoning steps.

Human approval and external callbacks

Never keep an invocation open while waiting for a person. Store the proposed action, stop processing, and use a Step Functions callback task or an application event to resume. Bind approval to the job, proposed action digest, approver, and expiry time. Revalidate authorization when resuming because permissions and input data may have changed.

Security and operations

Give the runtime role access only to the queue, table rows, artifact prefix, models, and tools it needs.
Encrypt artifacts, avoid secrets in prompts and logs, and define retention for intermediate data.
Treat tool output and retrieved documents as untrusted input. Validate schemas and require policy checks outside the model for consequential actions.
Record job ID, step ID, runtime session ID, model version, prompt/template version, tool calls, and result URI in traces.
Put bounded retries on transient failures, then route exhausted work to a dead-letter queue. Do not retry policy denials or malformed input.

Migration from a single long session

First inventory everything held only in process memory. Move business state and artifacts to durable stores. Divide the flow into restartable steps and add idempotency. Put waiting states in the orchestrator. Finally, kill workers during a staging run and verify the workflow resumes without duplicate side effects.

Evaluate the design with four tests: a retry after a model timeout, termination midway through a batch, approval after the original session has expired, and duplicate delivery of the same queue message. The job is durable only when all four produce one correct final outcome.

References

Reviewed against official documentation on 2026-08-01.

Run n8n Queue Mode on AWS ECS with Recoverable Operations

Yoonsoo Park — Wed, 20 Aug 2025 00:00:00 +0000

n8n queue mode separates HTTP/editor work from workflow execution. The scalable unit is not “two workers behind two load balancers.” It is a set of explicit n8n process roles sharing a database, Redis queue, encryption key, and versioned configuration.

This architecture is a starting point, not a claim that ECS is always better than n8n’s supported Kubernetes patterns or n8n Cloud.

Components and boundaries

Main/editor service: owns the editor UI, API, scheduling, and workflow activation. Keep it private to trusted users through SSO/VPN/identity-aware ingress where possible.
Webhook processors: receive production webhook traffic and enqueue executions. Expose only required webhook paths.
Workers: run queued executions. They do not need public ingress.
PostgreSQL: system of record for workflows, credentials metadata, and execution records. Use supported PostgreSQL versions, Multi-AZ where required, backups, and restore tests.
Redis: queue coordination. Configure the n8n-supported Redis mode and durability/failover appropriate to acceptable work loss.
Task runners: isolate user-supplied Code node execution according to current n8n guidance.

Use one Application Load Balancer with host/path routing unless separate load balancers provide a documented security, ownership, or scaling boundary. CORS is not the reason to split ingress; configure N8N_EDITOR_BASE_URL, WEBHOOK_URL, proxy trust, and allowed origins consistently.

Version and secrets

Pin the same n8n version or immutable image digest across main, webhook, workers, and runners. Never mix versions during steady state or deploy latest to production.

All roles need the same N8N_ENCRYPTION_KEY. Store it in AWS Secrets Manager and plan backup/restore separately; losing it can make stored credentials unreadable. Supply database and Redis authentication as ECS secrets, not plain environment values in a task definition or CI log. Use distinct task and execution roles with least privilege.

Representative environment names must be checked against the n8n version you pin:

1
2
3
4
5
6


EXECUTIONS_MODE=queue
DB_TYPE=postgresdb
DB_POSTGRESDB_HOST=<private endpoint>
QUEUE_BULL_REDIS_HOST=<private endpoint>
N8N_EDITOR_BASE_URL=https://n8n.example.com
WEBHOOK_URL=https://hooks.example.com

Do not copy an old Compose variable list without validating current n8n documentation. Configuration names and task-runner requirements evolve.

Networking

Run tasks, Postgres, and Redis in private subnets. ALB listeners terminate TLS with ACM. Restrict security groups by connection path: ALB to HTTP roles, ECS roles to database/Redis, and no direct public database access. Provide controlled outbound access for workflow integrations through NAT or approved egress/proxy paths, understanding that arbitrary workflows can exfiltrate data if their network and credential authority is broad.

Protect the editor more strongly than public webhook endpoints. Apply request limits and WAF rules only where they address measured threats. Verify n8n’s proxy and secure-cookie settings behind the ALB.

Scaling and reliability

Keep at least two tasks for roles that require availability across Availability Zones. Scale workers from queue depth and oldest-job age, capped by downstream API and database capacity; CPU alone does not describe backlog. Configure graceful shutdown so workers stop accepting jobs and finish or safely return work before ECS termination.

Health checks should test the correct role endpoint, but an ALB health check does not prove a worker can decrypt credentials, query Postgres, reach Redis, or run a workflow. Add synthetic workflows and alarms for queue age, failed executions, worker availability, database connections/storage, Redis memory/failover, ALB 5xx, and ECS deployment failure.

Upgrade and rollback

Read n8n release and migration notes; test every intermediate version required.
Back up PostgreSQL and the encryption key; perform periodic restore drills.
Clone production configuration into a non-production environment and run representative workflows.
Pin the new image, run database migrations through the documented n8n process, and deploy compatible roles in a controlled order.
Pause or drain work if the release requires it. Observe synthetic and real executions.
Roll back application images only when the database migration is backward compatible. Otherwise restore the pre-upgrade database and matching encryption key according to the tested plan.

Alternatives

n8n Cloud removes most infrastructure ownership. A single VM/Compose deployment is often simpler for personal workloads and can be reliable with backups and downtime tolerance. ECS fits teams already operating AWS container workloads. EKS adds Kubernetes ecosystem capabilities but also operational cost. Choose based on recovery objectives, concurrency, expertise, and compliance—not the word “serverless.”

Verified on 2026-08-01.

Primary sources

Kiro After General Availability: Specs, Agents, CLI, and Web

Yoonsoo Park — Tue, 22 Jul 2025 00:00:00 +0000

Kiro launched in preview in July 2025 and reached general availability in November 2025. It is no longer just a preview IDE with “vibe” and “spec” modes. The product now spans IDE and CLI workflows, team features, property-based testing, checkpoints, remote MCP, global steering, custom and parallel agents, and Kiro Web preview. Availability, models, credit accounting, and prices change, so use the live product and pricing pages for purchasing decisions.

Choose the interaction by task

Use specs when the work needs explicit requirements, design, tasks, and traceability. They help when a feature crosses components or when a team needs to review intent before implementation. A spec is not proof that the requirement is correct; review acceptance criteria, data, security, migration, and non-goals.

Use agentic chat for bounded exploration, diagnosis, and small edits where a full spec would add ceremony. Ask it to inspect current repository facts first and require changed-file and validation evidence.

Use Kiro CLI when terminal context, scripts, or remote environments matter. Use Kiro Web for asynchronous repository work and pull-request creation when its preview status and connected-repository permissions fit the task. Keep branch protection and human review; a generated PR is not an approval.

Persistent project context

Steering files capture durable conventions: architecture boundaries, build/test commands, naming, privacy, and release rules. Keep them short and version-controlled. Do not put secrets, customer data, personal preferences unrelated to the project, or frequently changing status in steering.

Hooks automate actions around events. They consume credits and can amplify mistakes, so start with read-only checks or formatting/tests. Avoid hooks that deploy, publish, delete, or broadly rewrite without an explicit approval boundary.

MCP connects tools and external context. Treat MCP servers as privileged software: review origin, permissions, data sent, authentication, and tool schemas. Remote content can contain prompt injection.

A reliable workflow

Open the intended repository/branch and inspect its instructions and dirty state.
Write a small task brief with goal, non-goals, constraints, acceptance tests, and rollback.
Use a spec for cross-cutting work; otherwise begin with a plan and targeted reads.
Keep edits small and review checkpoints before high-impact steps.
Run deterministic format, type, unit, integration, and build checks.
Inspect the diff and test negative/security cases.
Commit to a branch and use normal CI/review/release controls.

Property-based testing can derive general properties from specs and generate many cases, which is valuable for input spaces. It complements example tests; it does not replace integration, security, usability, or production acceptance.

Tradeoffs and evaluation

Specs improve alignment but can become stale or produce false confidence. Chat is fast but may drift across a large task. Parallel agents can reduce elapsed time when file ownership is disjoint, but increase conflicts and inconsistent assumptions. More tool access increases capability and risk.

Evaluate Kiro on representative repository tasks: success rate, escaped defects, reviewer edit distance, latency, credit/cost, security violations, and ability to recover. Compare against the team’s current workflow. Do not choose based only on a polished greenfield demo.

Migration from the preview-era workflow

Remove waitlist and fixed preview-limit claims; link live pricing.
Move durable repository guidance into reviewed steering files.
Convert reusable high-risk hooks to manual commands or approval-gated automation.
Review MCP servers and custom-agent permissions.
Add checkpoints, deterministic validation, and branch/PR review.
Re-evaluate IDE, CLI, and Web separately for data and repository access.
Re-run a small benchmark when models or credit policies change.

Verified on 2026-08-01.

Primary sources

AWS Vector Databases for RAG — A 2026 Architectural Decision Guide

Yoonsoo Park — Sun, 25 May 2025 02:30:00 -0400

Choosing a vector store on AWS used to be a five-way decision. With Amazon S3 Vectors in the picture, it’s now better framed as a question of which tier of the cost/latency curve your workload belongs to. This is an updated decision framework — what each option is good at, when it wins, and how they increasingly combine instead of compete.

Update note (2026): This post was first written in May 2025. I’ve since reworked it to add S3 Vectors, mark the services that have graduated from preview to general availability, and cut the date-stamped claims that aged badly. If you read the original five-service version, the biggest change is that “pick one database” is now mostly the wrong question.

The mental model: a cost/latency tier, not a beauty contest

Most “which vector DB should I use” guides line up services side by side as if you pick one and commit. In practice the AWS-native options now sort cleanly onto a cost vs. latency curve:

Tier	When it fits	AWS option
Hot / real-time	High QPS, sub-50ms p99, always-on	OpenSearch Service
Warm / transactional	Vectors next to relational data, ACID	Aurora / RDS PostgreSQL + pgvector
Cold / cost-first	Billions of vectors, infrequent or batch queries	S3 Vectors
Managed / fastest-to-ship	You want RAG, not a database	Bedrock Knowledge Bases
Graph-aware	Relationships matter as much as similarity	Neptune Analytics (GraphRAG)
Turnkey enterprise search	Connectors + access control, zero vector expertise	Kendra GenAI Index

The interesting shift since 2025 is that the top and bottom of this table now tier together: you keep hot vectors in OpenSearch and spill the long tail into S3 Vectors, instead of paying memory prices for cold data. More on that below.

Amazon S3 Vectors — the cost floor (the big addition)

This is the service that didn’t exist when I first wrote this guide, and it changes the economics enough to deserve top billing.

S3 Vectors is the first object store with native vector storage and query — you create vector indexes inside S3 and query them through a dedicated API, with no cluster to provision. AWS positions it as reducing the cost of uploading, storing, and querying vectors by up to 90% versus running an always-on vector database.

Key facts:

Scale: up to 2 billion vectors per index, 10,000 indexes per vector bucket — into the trillions of vectors per bucket.
Latency: warm queries land around ~100ms (sub-second), not the single-digit milliseconds of an in-memory engine. This is the tradeoff.
Consistency: strong consistency — a query always sees your most recently written vectors.
No infrastructure: pay-for-what-you-use, zero provisioning.

Where it fits: large, long-lived vector datasets that are queried infrequently or in batch — agent long-term memory, archival semantic search, “search everything we’ve ever ingested” corpora. It is explicitly not the choice for high-QPS real-time serving.

The integration that matters: S3 Vectors is natively wired into Bedrock Knowledge Bases (so a KB can use S3 Vectors as its store and cut RAG cost), and into OpenSearch Service for a tiered strategy — hot vectors in OpenSearch for low latency, the cold bulk in S3 Vectors for cost. That tiering is the single most useful architectural pattern to come out of this update.

Amazon OpenSearch Service — the scale and latency champion

OpenSearch remains the answer when you need high QPS at sub-second (often single-digit-ms) latency over very large vector counts. It’s the most operationally flexible option and the most proven at billion-scale.

Strengths:

Multiple engines (FAISS, Lucene, NMSLIB) with HNSW, IVF, and product quantization.
Aggressive compression: binary quantization (~32x) and product quantization, plus disk-optimized ANN that cuts memory needs substantially.
Serverless option with pay-per-OCU autoscaling for spiky traffic.
Metadata filtering integrated with k-NN for multi-tenancy.

Tradeoff: it’s a search cluster — you own the operational complexity and the memory bill. With S3 Vectors now available as a cold tier, the right move is increasingly OpenSearch for the hot set, S3 Vectors for the rest rather than sizing OpenSearch for your entire corpus.

Aurora / RDS PostgreSQL + pgvector — the integration master

If your vectors live next to relational data, pgvector is the path of least resistance: vector search and ACID transactions in one engine, with familiar tooling.

Strengths:

HNSW indexes, halfvec (50% memory reduction), sparse and binary vector types.
Iterative index scans (0.8.x) that prevent over-filtering when you combine WHERE clauses with vector search.
Graviton instances for better price/performance; Aurora Serverless v2 scales down for variable load.

Tradeoff: HNSW indexes want to live in memory, so instance sizing gets critical past a few million vectors. Best when relational + vector in one transactional store is worth more than peak vector throughput.

Amazon Bedrock Knowledge Bases — fastest path to RAG

If what you actually want is retrieval-augmented generation and not a vector database to operate, Bedrock Knowledge Bases is the managed front door: ingest → chunk → embed → retrieve → (optionally) generate, with the vector store abstracted away.

What’s matured since 2025:

It can sit on multiple backing stores — OpenSearch Serverless, Aurora pgvector, Neptune Analytics, and now S3 Vectors for cost-optimized RAG.
Multimodal ingestion, structured-data (natural-language-to-SQL) retrieval, reranking, custom chunking, and built-in RAG evaluation have moved from “preview” toward standard features.
GraphRAG (via Neptune Analytics) is available as a retrieval mode for relationship-rich corpora.

Tradeoff: less control over the retrieval internals. The migration path is the point: start on Bedrock KB to validate, drop to a self-managed store only when you’ve proven a specific need it can’t meet.

Amazon Neptune Analytics — the relationship expert

Neptune Analytics combines vector similarity with graph traversal, powering GraphRAG: multi-hop, relationship-aware retrieval that plain similarity search can’t do. For knowledge graphs and densely interconnected documents it materially improves answer quality on questions that depend on connections, not just nearest neighbors.

Tradeoff: higher modeling complexity than pure vector search, and it only pays off when your data genuinely has rich relationships. If “find similar chunks” is enough, this is overkill.

Amazon Kendra GenAI Index — turnkey enterprise search

Kendra delivers semantic enterprise search with no vector expertise required: managed connectors to enterprise sources, built-in document understanding, and native access control. The GenAI Index is tuned for RAG retrieval and can also feed Bedrock Knowledge Bases.

Tradeoff: the least flexible and not the cheapest at small scale, but the fastest time-to-value for “search our internal documents, respecting who’s allowed to see what.”

Decision shortcuts

High QPS, real-time, large scale → OpenSearch (spill cold vectors to S3 Vectors).
Billions of vectors, infrequent/batch queries, cost is the constraint → S3 Vectors.
Vectors alongside relational data, need ACID → Aurora/RDS pgvector.
You want RAG shipped this week, not a database to run → Bedrock Knowledge Bases.
Answers depend on relationships, not just similarity → Neptune Analytics (GraphRAG).
Enterprise document search with access control, no ML team → Kendra GenAI Index.

Anti-patterns to avoid

Sizing one hot store for your entire corpus. This was the default in 2025 because there was no good cold tier. With S3 Vectors, paying in-memory prices for rarely-queried vectors is now a choice, not a necessity — tier instead.
Over-engineering the first deployment. If Bedrock Knowledge Bases gets you to a working RAG demo, start there and migrate only when you’ve proven a concrete limitation.
Forcing every data type into one service. Hybrid is normal: hot content in OpenSearch, cold bulk in S3 Vectors, relationships in Neptune, structured data in pgvector. Pick per data shape, not per dogma.
Skipping quantization. Running full float32 vectors uncompressed wastes memory and money; binary/product quantization usually preserves quality at a fraction of the footprint.

Cheers! 🍺

A Practical Taxonomy for AI Agent Systems

Yoonsoo Park — Wed, 21 May 2025 00:00:00 +0000

“AI agent” and “agentic AI” do not have one universally enforced boundary. Vendors and researchers use the terms differently. A system does not become more capable merely because it is called agentic, and a multi-agent topology is not automatically more autonomous than one agent.

For design and governance, describe observable capabilities instead of choosing between two labels.

Six dimensions that matter

Tool authority: Can the model only retrieve information, or can it write data, send messages, deploy software, move money, or delete resources?
Planning horizon: Does it answer one turn, execute a bounded workflow, or pursue a goal across hours and resumptions?
Autonomy: Which steps require human approval? Can the system choose new goals, or only methods inside an approved goal?
State and memory: Is context limited to one request, persisted in a session, or extracted into long-term user or organizational memory?
Delegation topology: Is there one model/tool loop, a supervisor with specialists, peer-to-peer delegation, or a deterministic workflow calling models?
Environment uncertainty: Are actions applied to a sandbox, a reversible draft, or a live system with people and money?

Two systems with the same “agent” label can have completely different risk. A single agent with permission to refund customers is more consequential than five read-only agents summarizing documents.

Choose the smallest architecture

Start with a deterministic application calling a model for a narrow transformation. Add retrieval when current or private knowledge is required. Add tools when the model must act, but expose specific operations with validated inputs rather than a general shell or database credential. Add planning only when the task cannot be represented as a known workflow.

Use multiple agents when specialization creates a measurable benefit: separate context ownership, independently evaluated skills, security boundaries, or parallel work with disjoint outputs. Do not add agents just to imitate an organization chart. Every delegation adds latency, tokens, failure modes, context loss, and another authorization decision.

For reliable business processes, a workflow engine should usually own durable state, retries, deadlines, compensation, and human approvals. A model can recommend or execute a bounded step without becoming the system of record.

A decision record

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


goal: triage incoming support cases
tools:
 - read_case
 - draft_reply
forbidden:
 - send_reply
 - change_account
planning_horizon: one_case
memory: session_only
human_gate: approve_draft
rollback: discard_draft
success_metrics:
 - routing_accuracy
 - unsafe_action_rate
 - reviewer_edit_distance

This description is testable. “Build an agentic support system” is not.

Security and evaluation

Treat prompts, retrieved documents, web pages, tool output, and messages from other agents as untrusted data. Validate tool arguments server-side and authorize every action against the authenticated actor and current resource—not against text that says the user is allowed. Use least-privilege workload identity, egress controls, secret isolation, audit logs, cost/time budgets, and idempotency keys.

Evaluate each layer separately:

model quality on representative inputs;
retrieval recall and grounding;
tool selection and argument validity;
authorization denials and prompt-injection resistance;
end-to-end task success, latency, cost, and recoverability;
human escalation quality when confidence or policy is unclear.

Test duplicate events, partial failures, stale context, unavailable tools, malicious retrieved text, and a delegated agent returning an invalid result. A polished demo is not evidence of safe autonomy.

Migration from label-first architecture

Inventory every tool and classify its read/write and reversibility.
Record planning horizon, memory scope, identity propagation, and approval points.
Replace broad tool access with narrow typed operations.
Move durable workflow state out of model context.
Establish a single-agent baseline before adding delegation.
Add evaluation cases and explicit stop budgets.
Roll out read-only, then drafts, then narrowly approved actions.
Review whether each extra agent improves measured outcomes enough to justify complexity.

Verified on 2026-08-01.

Primary sources

Cognito and Salesforce OIDC Trust Topologies

Yoonsoo Park — Fri, 11 Apr 2025 00:00:00 +0000

“SSO between Cognito and Salesforce” describes two opposite trust directions. Configuration fails when the identity provider (IdP), relying party (RP), token issuer, and callback owner change halfway through the design. Choose one topology from the user journey and write it down before opening either console.

This guide was verified on 2026-08-01 against the official AWS documentation for Cognito user pools with OIDC providers, Cognito federation endpoints, and Cognito security practices, plus Salesforce guidance for External Client Apps and OIDC single logout.

Topology A: Cognito is the IdP, Salesforce is the RP

Use this when users should enter Salesforce with an identity represented by a Cognito user pool. Salesforce creates an OpenID Connect Authentication Provider that trusts Cognito. The browser starts at Salesforce, goes to the Cognito authorization endpoint, and returns to the exact callback URL generated by Salesforce.

Give the user pool a domain and an app client using the authorization-code grant.
In Salesforce, create an OpenID Connect Auth Provider. Copy its generated callback URL exactly into the Cognito app client’s allowed callback URLs.
Configure Salesforce from Cognito’s discovery metadata rather than guessing endpoint paths. Cognito publishes discovery under its issuer and signing keys through JWKS. Cache keys by kid, refresh them on an unknown key, and validate issuer, audience, signature, expiry, and nonce.
Request only needed scopes, normally openid plus approved profile claims.
Implement a Salesforce Registration Handler that maps an immutable external subject to an existing user or performs tightly controlled just-in-time (JIT) provisioning.

The Cognito app client is confidential when Salesforce authenticates to the token endpoint with a secret. Store that secret only in the platform configuration intended for the Auth Provider. Do not put it in browser code, source control, screenshots, or an Apex custom setting readable by ordinary users.

The Registration Handler must not match accounts by an unverified, mutable email address alone. Prefer the tuple of trusted issuer and sub, preserve that external identifier, allowlist acceptable tenant or group claims, and apply least-privilege profiles and permission sets. Decide what happens when a user is disabled at the source; JIT creation without deprovisioning produces stale access.

Topology B: Salesforce is the IdP, Cognito is the RP/broker

Use this when a Salesforce identity should sign users into an application that receives Cognito-issued tokens. Salesforce authorizes the Cognito OIDC client, Cognito validates Salesforce tokens and maps claims, then Cognito issues its own user-pool tokens to the application.

Configure My Domain and create a Salesforce External Client App for new OAuth integrations where Salesforce is the authorization server. Enable the authorization-code flow and the policy controls required by the org.
Register Cognito’s exact OIDC callback as the Salesforce callback. For a Cognito user-pool OIDC provider, AWS documents the callback in the form https://<user-pool-domain>/oauth2/idpresponse.
In Cognito, add Salesforce as an OIDC IdP. Use the Salesforce My Domain discovery document: https://<my-domain>.my.salesforce.com/.well-known/openid-configuration.
Confirm that discovery returns HTTPS authorization, token, user-info, and JWKS endpoints compatible with Cognito. AWS currently requires the provider’s supported client authentication behavior described in its OIDC IdP prerequisites.
Map Salesforce claims to mutable and required Cognito attributes deliberately. Cognito automatically maps the upstream OIDC sub into its federated identity; do not overwrite identity keys with display names.
Enable this IdP for the intended Cognito app client and initiate sign-in through Cognito managed login or its authorize endpoint. The application accepts Cognito tokens, not upstream Salesforce tokens.

External Client App policies should restrict who may authorize, scopes, session behavior, refresh-token use, and administrative approval. A public browser or native client must use authorization code with PKCE and must not contain a client secret. In this topology Cognito acts as a server-side OIDC client to Salesforce, so confirm the exact client-authentication method supported by both products rather than copying a public-client recipe.

Browser request controls

For application-to-Cognito authorization requests, use authorization code with PKCE (S256). Generate a high-entropy state value, bind it to the browser transaction, and compare it on return to prevent login CSRF. Generate and validate nonce for OIDC replay protection. Use exact HTTPS redirect URIs; do not allow wildcards, substring matching, or user-provided return origins.

Keep the post-login destination separate from redirect_uri. Store an allowlisted relative route server-side or in integrity-protected state. Never redirect directly to an arbitrary startURL, RelayState, or query-string URL supplied by a caller.

Claims, JIT, and authorization

OIDC proves an authentication event; it does not define the user’s application permissions. Document each required claim, its issuer, data type, mutability, and destination. Treat groups and roles as authorization input only after verifying the issuer and applying an allowlist. Minimize personally identifiable claims and avoid putting sensitive internal attributes in tokens visible to the browser.

Test existing-user linking, first login, changed email, duplicate email, disabled user, missing claim, unexpected tenant, and a user with no authorized role. JIT provisioning should fail closed and produce an auditable event. Define deprovisioning through lifecycle automation, short sessions, token revocation, or a combination appropriate to the risk.

Logout is a separate protocol decision

Clearing the local application cookie does not end the Cognito, Salesforce, or upstream corporate IdP session. Define which sessions a “Log out” action should end. Cognito exposes a managed-login logout endpoint; Salesforce documents front-channel OIDC single logout when Salesforce is the provider. Product support is not symmetric, so test RP-initiated logout, IdP-initiated logout where supported, post-logout redirect allowlists, refresh-token revocation, and login from a shared browser.

Migration and verification checklist

Draw browser, app, Cognito, and Salesforce with arrows for authorize, callback, token, user-info, and logout.
Record issuer, discovery URL, JWKS URL, client owner, exact callbacks, scopes, and secret owner.
Start in non-production orgs and use test accounts with no privileged profile.
Verify PKCE, state, nonce, issuer, audience, expiry, signature, and key rotation.
Review claim mappings and JIT/deprovisioning with Salesforce and identity administrators.
Test callback mismatch, invalid state/nonce, expired code, unknown kid, disabled user, logout, and rollback.
Capture audit logs from Cognito, Salesforce Login History, and the application without logging codes, tokens, or secrets.
Promote exact configuration through infrastructure or change control; do not retype production callbacks from memory.

The acceptance gate is a complete browser trace in the chosen topology, least-privilege authorization after login, predictable logout, and a documented rollback that disables the new trust without locking out administrators.

Ruby Syntax and Core Collection Methods for Beginners

Yoonsoo Park — Fri, 31 Jan 2025 00:00:00 +0000

Ruby Syntax and Built-in Methods

This is a Ruby language reference, not a Rails tutorial. Rails builds on Ruby, but it adds its own framework conventions, APIs, and lifecycle.

The examples were reviewed on 2026-08-01 against the official Ruby syntax documentation and Ruby in Twenty Minutes. Check the official Ruby documentation index and maintenance status before selecting a version for a new project. The examples use syntax available in maintained modern Ruby releases; pin the project’s version in development and CI rather than relying on the macOS system Ruby.

Introduction

Ruby is an object-oriented language in which expressions return values and blocks are central to collection APIs. The Python comparisons below are orientation aids, not claims that the two object models are identical.

Class Definitions

Ruby Syntax

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


class Person
 def initialize(name, age)
 @name = name # Instance variable; note that Ruby uses `@` to denote instance variables
 @age = age
 end

 def introduce
 "Hi, my name is #{@name} and I am #{@age} years old."
 end
end

# Usage
person = Person.new("Alice", 30)
puts person.introduce

Python Equivalent

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


class Person:
 def __init__(self, name, age):
 self.name = name
 self.age = age

 def introduce(self):
 return f"Hi, my name is {self.name} and I am {self.age} years old."

# Usage
person = Person("Alice", 30)
print(person.introduce())

Ruby instance variables use an @ prefix. Python stores comparable state through attributes on self.

Inheritance

Ruby Implementation

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


class Employee < Person
 def initialize(name, age, position)
 super(name, age) # Calls parent class's constructor
 @position = position # then we set the instance variable
 end

 def work
 "#{@name} is working as a #{@position}."
 end
end

Python Implementation

1
2
3
4
5
6
7


class Employee(Person):
 def __init__(self, name, age, position):
 super().__init__(name, age)
 self.position = position

 def work(self):
 return f"{self.name} is working as a {self.position}."

Ruby writes superclass inheritance with <; Python places base classes in parentheses.

Function Definitions

Ruby Methods

1
2
3
4
5
6
7
8
9


class Calculator
 def add(a, b = 0) # Default parameter
 a + b
 end
end

calc = Calculator.new
puts calc.add(5, 10) # => 15
puts calc.add(7) # => 7 (uses default value)

Python Methods

1
2
3
4
5
6
7


class Calculator:
 def add(self, a, b=0): # Default parameter
 return a + b

calc = Calculator()
print(calc.add(5, 10)) # => 15
print(calc.add(7)) # => 7 (uses default value)

Variables and Scope

Ruby Variables

1
2
3
4
5


def demonstrate_variables
 local_var = "I am local" # Local variable
 @instance_var = "Instance scope" # Instance variable
 [local_var, @instance_var]
end

Ruby also has class variables (@@name) and globals ($name), but both introduce wider mutable state and should not be the default for ordinary application data. Prefer explicit objects, constants for immutable shared values, and class-instance variables when class-owned state is genuinely required.

Python Variables

1
2
3
4
5


def demonstrate_variables(self):
 local_var = "I am local" # Local variable
 self.instance_var = "Instance scope" # Instance variable
 # Class variables in Python use class namespace
 # Global variables use global keyword

Loops and Iteration

Ruby Loops

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


# Each iterator
[1, 2, 3].each do |number|
 puts number
end

# For loop
for number in 1..5
 puts number
end

# While loop
i = 0
while i < 5
 puts i
 i += 1
end

# Until loop (Ruby-specific)
i = 0
until i >= 5
 puts i
 i += 1
end

Built-in Methods

String Methods

1
2
3
4
5
6
7
8


# Common string operations
str = "Hello, World!"
str.length # => 13
str.upcase # => "HELLO, WORLD!"
str.downcase # => "hello, world!"
str.capitalize # => "Hello, world!"
str.reverse # => "!dlroW ,olleH"
str.split(",") # => ["Hello", " World!"]

Array Methods

Ruby arrays can contain objects of different classes, like Python lists. That flexibility is a Ruby language property and does not depend on Rails.

1
2
3
4
5
6
7


# Mixed type array examples
mixed_array = [1, "hello", 3.14, true, [1, 2], {name: "John"}]
# You can add different types at any time
mixed_array.push(:symbol) # Adds a Symbol
mixed_array << nil # Adds nil using the shovel operator
mixed_array.unshift(42.0) # Adds a Float at the beginning
# These operations are valid; mixed collections still require clear application contracts.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


# Array operations
arr = [1, 2, 3, 4, 5]
arr.length # => 5
arr.first # => 1
arr.last # => 5
arr.include?(3) # => true

# Mutating operations change their receiver
arr.push(6) # arr => [1, 2, 3, 4, 5, 6]
arr.pop # => 6; arr => [1, 2, 3, 4, 5]
arr.unshift(0) # arr => [0, 1, 2, 3, 4, 5]
arr.shift # => 0; arr => [1, 2, 3, 4, 5]
arr.insert(2, 99) # arr => [1, 2, 99, 3, 4, 5]
arr.delete_at(2) # => 99; arr => [1, 2, 3, 4, 5]

# delete removes every matching value and returns the argument when found
values = [0, 1, 0, 2]
values.delete(0) # => 0; values => [1, 2]

# delete_if removes values matching the block
numbers = [1, 2, 3, 4, 5]
numbers.delete_if { |n| n.even? } # numbers => [1, 3, 5]

# clear removes all values
numbers.clear # numbers => []

Hash Methods

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


# Hash operations
hash = { name: "John", age: 30 }
hash.keys # => [:name, :age]
hash.values # => ["John", 30]
hash[:name] # => "John"
hash.merge(city: "New York") # => {:name=>"John", :age=>30, :city=>"New York"}
hash.delete(:age) # => 30 # Deletes the key-value pair with the specified key and returns the value that was deleted

# Remove key-value pairs based on a condition
hash = { name: "John", age: 30, role: "Developer", level: "Senior" }
hash.delete_if { |k,v| v == "John" } # => {:age=>30, :role=>"Developer", :level=>"Senior"} # Removes all pairs where value is "John"

# Remove nil values from hash
hash = { name: "John", age: 30, title: nil, department: nil }
hash.compact # => {:name=>"John", :age=>30} # Returns new hash with nil values removed
hash.compact! # Removes nil values from original hash permanently

# how to remove all key-value pairs from the hash
hash.clear # => {} # Removes all key-value pairs from the hash

Numeric Methods

1
2
3
4
5
6
7
8


# Numeric operations
num = 42
num.even? # => true
num.odd? # => false
(-num).abs # => 42 # The - operator negates num to -42, then abs returns absolute value back to 42
3.14.round # => 3
3.14.ceil # => 4
3.14.floor # => 3

Enumerable Methods

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


# Collection operations
numbers = [1, 2, 3, 4, 5]

# Map/Collect
numbers.map { |n| n * 2 } # => [2, 4, 6, 8, 10] # |n| is a block parameter, similar to a function parameter
 # It represents each element from 'numbers' as the map iterates
 # You can name it anything, e.g. |num| or |x|

# Select/Filter
numbers.select { |n| n.even? } # => [2, 4]

# Reduce/Inject
numbers.reduce(:+) # => 15 # Adds all numbers in array: 1 + 2 + 3 + 4 + 5 = 15
numbers.inject(:+) # => 15 # Same as reduce
numbers.inject(0) { |result, element| result + element } # => 15 # More explicit version where:
 # - 0 is the initial value
 # - result is always the accumulated value from previous iterations
 # - element is the current array element being processed
 # The block parameters |result, element| follow a convention:
 # - First parameter is always the accumulator/result
 # - Second parameter is always the current element

# Sort
numbers.sort # => [1, 2, 3, 4, 5] # Returns ascending order
numbers.sort.reverse # => [5, 4, 3, 2, 1] # Sorts numbers in descending order

# Reverse
numbers.reverse # => [5, 4, 3, 2, 1] # Reverses the order of the array

# First/Last
numbers.first # => 1 # Returns the first element of the array

# Any/All
numbers.any? { |n| n > 3 } # => true # Returns true because at least one number (4,5) is greater than 3
numbers.all? { |n| n < 6 } # => true # Returns true because every number (1,2,3,4,5) is less than 6

Use ruby -c file.rb for a syntax check and run examples with the same Ruby version used by the project. For API details, consult the documentation for that exact release because core methods and keyword behavior can evolve across major versions.

Build a Privacy-Aware Meeting Transcription Workflow with Amazon Transcribe

Yoonsoo Park — Fri, 24 Jan 2025 00:00:00 +0000

Amazon Transcribe can turn recorded or streaming audio into text, with features such as speaker partitioning, custom vocabulary, and PII handling for supported languages and modes. The hard part of a meeting workflow is not starting a transcription job. It is deciding whether recording is permitted, protecting the audio and transcript, checking accuracy, and deleting data on schedule.

Establish the policy first

Recording and transcribing people can trigger consent, employment, contractual, privacy, and sector-specific requirements. Determine the applicable policy with the responsible legal/privacy owner. Notify participants in a form they can understand, provide an alternative where required, and do not silently repurpose transcripts for model training or performance monitoring.

Define purpose, access, storage Region, retention, deletion, and downstream AI use before collection. A transcript is not less sensitive than audio; it may be easier to search and exfiltrate.

A bounded batch workflow

Upload audio to a private S3 input prefix using TLS and least-privilege access.
Start a uniquely named Transcribe job with the correct language, media format, speaker settings, and optional vocabulary.
Write output to a private destination you control rather than relying on a temporary service URL.
Validate job status and output schema, then record a non-sensitive job ID.
Run human review for names, numbers, decisions, and action items before treating the transcript as authoritative.
Apply retention and deletion to audio, raw transcript, corrected transcript, summaries, logs, and backups.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


import boto3
from uuid import uuid4

client = boto3.client("transcribe", region_name="us-east-1")
job_name = f"meeting-{uuid4()}"
client.start_transcription_job(
 TranscriptionJobName=job_name,
 LanguageCode="en-US",
 MediaFormat="mp4",
 Media={"MediaFileUri": "s3://private-input/meeting.mp4"},
 OutputBucketName="private-transcripts",
 Settings={"ShowSpeakerLabels": True, "MaxSpeakerLabels": 8},
)

The caller role should access only the required prefixes and Transcribe actions. Use S3 Block Public Access, encryption, bucket policies, audit logging, and lifecycle rules. Do not put attendee names or meeting titles in public object keys or job names.

Summaries and GenAI

Amazon Transcribe Call Analytics supports additional call-focused insights and generative call summarization in supported scenarios. For ordinary meetings, a separate model may summarize a reviewed transcript, but first check service approval and data policy. Ground the summary in transcript segments and retain citations or timestamps. Ask the model to separate decisions, proposed ideas, owners, deadlines, and unresolved questions. Require a participant or meeting owner to approve consequential actions.

PII redaction reduces some exposure; it is not anonymization and may miss context-specific identifiers. Do not send the raw transcript to arbitrary consumer AI tools. Minimize input to the segments needed for the task.

Accuracy and failure modes

ASR quality varies with accents, overlap, microphones, noise, domain terms, and language switching. Speaker labels distinguish channels or inferred speakers; they do not prove a person’s legal identity. Custom vocabularies can improve domain words but need evaluation.

Test clipped audio, silent files, more speakers than configured, language mismatch, overlapping speech, failed jobs, duplicate uploads, and deletion failures. Make processing idempotent and alarm on jobs stuck or failed. Never equate a fluent summary with an exact record.

Alternatives

Local transcription may fit stricter data-boundary requirements but shifts model, device, security, and accuracy operations to the team. A meeting platform’s built-in transcription may offer better participant notice and speaker mapping. Transcribe is a good fit when AWS storage/integration, scale, and configurable processing matter.

Migration checklist

Add a consent and approved-use gate before upload.
Replace broad AWS credentials with a role scoped to input/output prefixes.
Enable private storage, encryption, lifecycle, audit, and deletion verification.
Add speaker/language settings and representative accuracy tests.
Review and correct transcripts before downstream automation.
Add citations and human approval to summaries and actions.
Delete old local transcript copies and revoke obsolete access.

Verified on 2026-08-01.

Primary sources

Debug AWS Amplify and Cognito Sign-In Flows

Yoonsoo Park — Mon, 30 Dec 2024 00:00:00 +0000

Adding authFlowType: "USER_PASSWORD_AUTH" is not a universal fix for an Amplify sign-in error. Cognito must allow that flow on the app client, and it sends the user’s password to the service over TLS rather than using Secure Remote Password (SRP). Amplify’s default SRP flow is usually the better starting point for username/password authentication.

The reliable way to debug sign-in is to align four layers: Amplify configuration, Cognito app-client settings, the selected authentication flow, and the multi-step state machine returned by Amplify Auth.

Configure without embedding secrets

A public React Native or browser application is a public client. It cannot protect a Cognito app-client secret. Create an app client without a secret and restrict callback/sign-out URLs and OAuth flows to the actual application.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


import { Amplify } from "aws-amplify";

Amplify.configure({
 Auth: {
 Cognito: {
 userPoolId: required("EXPO_PUBLIC_COGNITO_USER_POOL_ID"),
 userPoolClientId: required("EXPO_PUBLIC_COGNITO_CLIENT_ID"),
 signUpVerificationMethod: "code",
 },
 },
});

Fail at startup when configuration is missing. A client ID and user pool ID are identifiers, not secrets, but do not log tokens, passwords, authorization codes, or full authentication responses.

Start with SRP and handle `nextStep`

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


import { signIn, confirmSignIn } from "aws-amplify/auth";

const result = await signIn({ username, password });

switch (result.nextStep.signInStep) {
 case "DONE":
 break;
 case "CONFIRM_SIGN_IN_WITH_TOTP_CODE":
 case "CONFIRM_SIGN_IN_WITH_SMS_CODE":
 case "CONFIRM_SIGN_IN_WITH_EMAIL_CODE":
 // Ask the user for the challenge response, then:
 // await confirmSignIn({ challengeResponse: code });
 break;
 case "CONFIRM_SIGN_IN_WITH_NEW_PASSWORD_REQUIRED":
 // Collect and validate the new password and required attributes.
 break;
 case "RESET_PASSWORD":
 case "CONFIRM_SIGN_UP":
 // Route to the corresponding recovery or confirmation flow.
 break;
 default:
 // Show a recoverable UI and record only a sanitized error code.
 break;
}

The exact nextStep variants depend on the Amplify version and enabled Cognito features. Use the installed package types and current documentation rather than assuming every successful credential check returns DONE.

When `USER_PASSWORD_AUTH` is justified

Select it only when a documented integration requires it and the Cognito app client explicitly enables ALLOW_USER_PASSWORD_AUTH.

1
2
3
4
5


await signIn({
 username,
 password,
 options: { authFlowType: "USER_PASSWORD_AUTH" },
});

Tradeoff: this flow is simple and compatible with some migrations, but SRP avoids sending the password itself to Cognito. CUSTOM_WITHOUT_SRP is for a configured custom authentication challenge, not a generic fallback. Hosted UI/managed login with authorization code and PKCE can reduce the amount of authentication UI the app owns and is often preferable for federation.

A diagnostic sequence

Confirm the app points to the expected Region, user pool, and app client.
Inspect the app client’s allowed explicit auth flows; do not enable several flows merely to hide the error.
Check whether the user is confirmed, disabled, forced to reset a password, or subject to MFA.
Confirm the username alias used by the pool: username, email, or phone.
Verify network reachability and device clock, then collect a sanitized Amplify error name and Cognito request ID.
Reproduce with a dedicated test user in a non-production pool whose settings match production.

Avoid converting every exception into “unknown.” Map known states to user-safe messages while preserving a non-sensitive diagnostic code for operators. Do not reveal whether an arbitrary email exists if that conflicts with the account-enumeration policy.

Authentication tests need a cleanup strategy. Create purpose-specific users rather than sharing one account across parallel tests, keep MFA seeds and recovery channels in approved test-only storage, and delete or reset test identities predictably. Test against a pool configuration produced from the same infrastructure definition as production; a hand-edited test pool can make the application look correct while a required explicit auth flow or callback URL differs in production.

Migration and verification checklist

Upgrade to a supported Amplify v6 release and use modular aws-amplify/auth imports.
Remove app-client secrets from public applications.
Remove forced USER_PASSWORD_AUTH unless the flow is explicitly required and allowed.
Implement sign-up confirmation, MFA, new-password, reset-password, and sign-out paths.
Test invalid password, unknown user, disabled user, unconfirmed user, expired code, resend, MFA, and token refresh.
Verify app restart/session restoration and global sign-out behavior.
Redact logs and monitor Cognito/CloudWatch events under the approved privacy policy.

Verified on 2026-08-01.

Primary sources

A Safe Terraform Init, Plan, and Apply Workflow

Yoonsoo Park — Tue, 24 Dec 2024 00:00:00 +0000

terraform init, plan, and apply are not three maturity levels. They perform different parts of one workflow: initialize a working directory, calculate a proposed change, and execute an approved change.

Initialize reproducibly

Run terraform init in a new checkout and after changing provider requirements, modules, or backend configuration. It installs providers/modules, prepares the backend, and writes dependency selections to .terraform.lock.hcl.

1
2
3


terraform init
terraform fmt -check -recursive
terraform validate

Commit .terraform.lock.hcl for a root configuration so CI and teammates use reviewed provider selections. Constrain Terraform and provider versions. Do not commit .terraform/, state files, plan files, or credentials.

Changing a backend can migrate state. Back up and inspect the current state location, authenticate to both backends, and review the migration prompt. -reconfigure and -migrate-state solve different problems; do not choose one blindly in automation.

Plan against the right state

terraform plan refreshes relevant remote objects and compares them with configuration and state. A clean plan means “no difference detected for this configuration, state, credentials, and refresh,” not that the infrastructure is secure or complete.

For an approved deployment pipeline, save the reviewed plan:

1
2
3


terraform plan -out=release.tfplan
terraform show release.tfplan
terraform apply release.tfplan

The saved plan can contain sensitive values and is tied to the configuration, state, provider selections, and environment used to create it. Treat it as a protected, short-lived artifact. Do not generate it on one untrusted machine and apply it much later elsewhere.

Always inspect replacements and destroys, IAM broadening, network exposure, data migration, and cost-sensitive changes. A textual plan review is strongest when policy checks and tests enforce known invariants.

State and environment boundaries

Use a remote backend with locking and encryption for team workflows, restrict state access, and version/backup it according to the backend. State often contains sensitive values even when configuration marks outputs sensitive.

Terraform CLI workspaces are separate state instances in one working directory/backend. They are useful for temporary or closely related copies, but they are not strong isolation for production environments that need different credentials and access controls. Prefer separate root configurations/backends or appropriately isolated HCP Terraform workspaces for those boundaries, sharing reusable modules rather than one state for everything.

`-target` is exceptional

Resource targeting is for exceptional recovery or troubleshooting, not routine dependency ordering, partial environment deployment, or a faster test cycle. Terraform’s dependency graph already determines order. A targeted plan omits unrelated changes and can produce a misleading view of policy or cost.

When an exceptional target is approved:

1
2
3


terraform plan -target=aws_instance.example
# Review and apply the exceptional operation.
terraform plan

Finish with a full plan and reconcile configuration/state. If teams repeatedly need targeting, split the configuration along lifecycle and ownership boundaries.

Apply and rollback

Without a saved plan, terraform apply creates a new plan and asks for confirmation. -auto-approve belongs only in controlled automation with preceding policy and approval gates. It is not a safe local shortcut for production.

Terraform has no universal rollback command. Revert configuration and apply another reviewed plan when the provider supports reversal. Stateful replacements and schema changes may require backups, restore procedures, or application migration. Test those paths before deployment.

Verification checklist

Confirm binary/version, backend, workspace, cloud account, and caller identity.
Run format check, validation, tests/policy checks, and a full plan.
Review destroys, replacements, permissions, exposure, state moves, and unknown values.
Apply exactly the saved plan in the same trusted pipeline.
Run service-level smoke tests and observe alarms after apply.
Run a final plan to detect unexpected drift.
Store evidence and delete the sensitive plan artifact according to policy.

Official documentation reviewed on 2026-08-01:

DNS and Email Authentication Without the Misleading Shortcuts

Yoonsoo Park — Mon, 25 Nov 2024 00:00:00 +0000

DNS publishes routing and policy data. It does not perform an HTTP redirect, prove that every sender is trustworthy, or guarantee email delivery. Understanding the boundary of each record prevents configurations that look correct but fail authentication or create outages.

Common DNS records

A / AAAA: map a hostname to an IPv4 or IPv6 address.
CNAME: aliases one DNS name to another canonical name. It is not a browser redirect and normally cannot coexist with other data at the same owner name. DNS providers may offer ALIAS/ANAME-style flattening at the zone apex; that is provider behavior, not a CNAME at the apex.
MX: identifies mail exchangers for a domain. A lower preference number is tried first. Multiple MX records help only when they lead to genuinely independent, correctly configured delivery paths; a fake “backup MX” can weaken filtering or queue mail incorrectly.
TXT: carries arbitrary text used by ownership checks and email policies. Publishing several unrelated TXT records is normal, but a domain must not publish multiple SPF records.

SPF: authorize sending infrastructure

SPF evaluates whether the connecting mail server is authorized for the RFC5321.MailFrom/return-path domain. It does not by itself authenticate the visible From header. Keep one SPF record per domain, end with an intentional qualifier, and watch the RFC-defined DNS lookup limit. Flattening provider ranges can become stale, while excessive include chains can produce permerror.

Example:

1

example.com. TXT "v=spf1 include:_spf.example-sender.com -all"

Use a subdomain for a third-party sender when it reduces blast radius, and remove providers when they are no longer used.

DKIM: sign messages

DKIM adds a cryptographic signature. The receiver retrieves the public key at a selector such as selector1._domainkey.example.com. Protect the private key at the sender, use supported key sizes, rotate selectors, and keep an old selector published until messages signed with it have aged out.

AWS SES Easy DKIM can generate and rotate keys, but the DNS records must remain correct. “Three CNAMEs” is an SES implementation detail, not the definition of DKIM.

DMARC: require alignment and publish handling policy

DMARC passes when at least one of SPF or DKIM both passes and aligns with the visible From domain. It then tells receivers the requested policy and where to send aggregate reports.

1

_dmarc.example.com. TXT "v=DMARC1; p=none; rua=mailto:dmarc@example.com; adkim=r; aspf=r; pct=100"

Start with monitoring only after the mailbox and privacy handling for reports are ready. Inventory legitimate senders, fix alignment, then move deliberately to quarantine and reject. p=none gathers data but does not ask receivers to block failing mail. Receiver behavior and local policy can still vary.

Safe change procedure

Inventory every service sending with the domain, including marketing, support, billing, alerts, and forwarding.
Query current authoritative DNS and record TTLs.
Configure DKIM and an aligned return-path for each sender.
Publish one reviewed SPF policy and a DMARC monitoring record.
Validate syntax with authoritative queries and send test messages to independent receivers.
Inspect Authentication-Results headers and aggregate reports.
Tighten DMARC gradually, monitoring false positives and forwarded/list mail.
Document owner, purpose, provider, selector, and removal date for every record.

DNS caching means rollback is not instant. Lowering TTL only helps after the previous TTL has elapsed. DNSSEC protects authenticity of DNS responses when correctly deployed, but it does not replace SPF, DKIM, or DMARC.

Official standards reviewed on 2026-08-01:

Working with VS Code Multi-root Workspaces

Yoonsoo Park — Tue, 05 Nov 2024 00:00:00 +0000

Learn how to efficiently manage multiple project folders in Visual Studio Code using multi-root workspaces. Discover setup tips, best practices, and advanced configurations for improved development workflow and knowledge management.

Visual Studio Code

As developers, juggling multiple projects or working with distributed codebases is a common challenge. Visual Studio Code’s multi-root workspaces feature offers an elegant solution to this problem, allowing you to manage multiple folders within a single editor window. Let’s dive into how this powerful feature can transform your development workflow.

What Makes Multi-root Workspaces Special?

Multi-root workspaces remain supported. Prefer relative folder paths in shared .code-workspace files, keep machine-specific secrets out of workspace settings, and confirm that each extension supports folder-scoped configuration.

Think of multi-root workspaces as your digital workspace organizer. Instead of cluttering your taskbar with multiple VS Code windows or constantly switching between different project folders, you can have everything you need in one place. This feature is particularly valuable for:

Full-stack developers working with separate frontend and backend codebases
Teams managing microservices architectures
Developers maintaining documentation alongside their code
Anyone working with related projects spread across different locations

Unified knowledge folders

Integrating with Obsidian and iCloud

One of the most powerful applications of multi-root workspaces is creating a unified knowledge management system that works seamlessly across all your devices. Here’s why this combination is particularly powerful:

Single Source of Truth:
- Keep your Obsidian vault in iCloud while maintaining direct access through VS Code
- Access the same knowledge base whether you’re on your work laptop, personal computer, or mobile device
- Ensure your documentation and notes are always in sync across all platforms
Enhanced GenAI Interactions:
- Maintain a structured record of your progress and learning
- Use your knowledge base as context when interacting with AI tools
- Avoid repeating yourself in AI conversations by referencing your documented progress
- Create more meaningful and context-aware AI interactions
Progressive Documentation:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "folders": [
 {
 "path": "~/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault",
 "name": "Knowledge Base"
 },
 {
 "path": "./current-project",
 "name": "Active Project"
 }
 ]
}

Workflow Integration:
- Track project progress alongside your knowledge base
- Reference and update documentation in real-time as you code
- Maintain project-specific notes that sync across all devices
- Create living documentation that evolves with your understanding
AI-Assisted Knowledge Management:
- Use your documented progress to generate more relevant AI responses
- Maintain context across different AI conversations
- Build upon previous learnings and discoveries
- Create a feedback loop between your code, documentation, and AI interactions

Setting Up Your Multi-root Workspace

There are two main approaches to creating a multi-root workspace:

Quick Setup Method

Launch VS Code with your main project
Navigate to File > Add Folder to Workspace
Select additional folders you want to include
Save your workspace configuration

Professional Setup Method

Create a .code-workspace file with this structure:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 "folders": [
 {
 "path": "/path/to/your/primary/project"
 },
 {
 "path": "/path/to/your/secondary/folder"
 }
 ],
 "settings": {}
}

Advanced Configuration Tips

1. Portable Workspace Configuration

Make your workspace more shareable by using relative paths:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


{
 "folders": [
 {
 "path": ".",
 "name": "Main Project"
 },
 {
 "path": "../docs",
 "name": "Documentation"
 }
 ]
}

2. Folder-Specific Settings

Customize settings for different project folders:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


{
 "folders": [
 {
 "path": "./client",
 "name": "Frontend"
 },
 {
 "path": "./server",
 "name": "Backend"
 }
 ],
 "settings": {
 "./client": {
 "editor.tabSize": 2
 },
 "./server": {
 "editor.tabSize": 4
 }
 }
}

3. Knowledge Base Integration

Configure your workspace to include your Obsidian vault:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


{
 "folders": [
 {
 "path": "~/Library/Mobile Documents/iCloud~md~obsidian/Documents/MyVault",
 "name": "Knowledge Base"
 },
 {
 "path": "./project1",
 "name": "Current Project"
 },
 {
 "path": "../reference-projects",
 "name": "Reference Code"
 }
 ],
 "settings": {
 "files.exclude": {
 "**/.obsidian": true
 }
 }
}

Best Practices for Multi-root Workspaces

Organize Thoughtfully: Group related projects together for logical workflow
Monitor Performance: Keep the number of folders reasonable to maintain VS Code’s responsiveness
Use Clear Naming: Give each folder a descriptive name in the workspace configuration
Version Control: Consider sharing your workspace configuration with team members
Search Smartly: Use the folder: filter in search to target specific projects

Avoiding Common Pitfalls

Search Scope: Be mindful that searches include all workspace folders by default
Extension Compatibility: Verify that your essential extensions work well with multi-root workspaces
Resource Management: Close unused folders to maintain optimal performance

Best Practices for Knowledge-Driven Development

Consistent Documentation: Update your knowledge base as you code
AI-Ready Notes: Structure your documentation to be easily referenced in AI conversations
Progressive Refinement: Regularly review and update your notes based on new learnings
Cross-Platform Sync: Ensure your workspace configuration works across different devices
Context Preservation: Maintain links between related pieces of knowledge

Real-world Applications

Multi-root workspaces excel in scenarios like:

Managing frontend and backend codebases in full-stack applications
Keeping documentation and code in sync
Working with multiple microservices
Maintaining configuration files alongside active projects
Building a personal knowledge management system
Creating AI-ready documentation
Maintaining a learning journal alongside active projects
Tracking project progress across multiple devices

Looking Ahead

As modern development becomes increasingly complex, tools like VS Code’s multi-root workspaces become essential for maintaining productivity. This feature continues to evolve with each VS Code release, offering new capabilities for managing complex development environments.

Understanding Git Ignore Patterns - .gitignore vs .git/info/exclude

Yoonsoo Park — Fri, 01 Nov 2024 00:00:00 +0000

Learn when to use .git/info/exclude instead of .gitignore for managing ignored files in Git, with practical examples and use cases

Git Documentation

When working with Git, we often need to specify files and directories that should be ignored by source control. While .gitignore is the most commonly used method, Git provides another powerful but lesser-known option: .git/info/exclude. Let’s explore both approaches and understand when to use each one.

The Traditional Approach: .gitignore

The .gitignore file is the standard way to specify which files Git should ignore. It’s:

Committed to the repository
Shared with all collaborators
Part of the project’s source control
Ideal for project-wide ignore patterns

The Hidden Gem: .git/info/exclude

.git/info/exclude serves a similar purpose but with some key differences. This file:

Lives inside the .git directory
Is not committed to the repository
Remains local to your machine
Doesn’t affect other collaborators

When to Use .git/info/exclude

Here are several scenarios where using .git/info/exclude makes more sense than .gitignore:

Personal IDE Settings
- You use a different IDE than your team
- Example: Ignoring VSCode settings while others use IntelliJ
```
.vscode/
```
Local Development Tools
- You have specific development tools that others don’t use
- Example: Local debugging tools or profilers
```
debug-tools/
my-profiler.log
```
Machine-Specific Build Outputs
- Custom build directories that vary by developer
```
my-custom-build/
local-dist/
```
Personal Test Files
- Test files you create for local experimentation
```
my-test-*.js
scratch/
```
Temporary Working Files
- Files you generate during development but don’t want to share
```
temp-*.txt
working-draft/
```

Real-World Example

Let’s say you’re working on a Node.js project where:

The team uses .gitignore for common patterns:
```
node_modules/
dist/
.env
```

But you personally:

Use VSCode for debugging
Have a custom build script
Keep local notes

Instead of polluting the project’s .gitignore, you can add to .git/info/exclude:

# Personal IDE
.vscode/
launch.json
# Custom build output
my-build/
build-*.log
# Personal notes
dev-notes.md
TODO.txt

Benefits of Using .git/info/exclude

Clean Repository
- Keep the project’s .gitignore focused on truly project-wide patterns
- Avoid cluttering with personal preferences
No Conflicts
- Your ignore patterns won’t conflict with other developers’ workflows
- No need for team discussions about personal ignore patterns
Flexibility
- Easily modify ignore patterns without creating commits
- Experiment with different tools without affecting the team
Privacy
- Keep your working methods private
- Don’t expose personal tools or workflows

Best Practices

Use .gitignore for:
- Project-wide ignore patterns
- Framework-specific files
- Common development artifacts
Use .git/info/exclude for:
- Personal tooling
- Local development artifacts
- Machine-specific patterns
- Temporary working files

Creating and Editing .git/info/exclude

Git reads .git/info/exclude automatically. Do not point core.excludesFile at it; that setting is for a separate user-level excludes file. Ignore rules never untrack a path that is already committed.

To start using .git/info/exclude:

1
2
3
4
5


# Open the file in your default editor
git config core.editor "code" # If using VSCode

# Or edit directly
vim .git/info/exclude

Remember that the syntax is identical to .gitignore, so all your existing knowledge transfers over.

Conclusion

While .gitignore remains the primary tool for specifying ignore patterns in Git, .git/info/exclude provides a valuable complement for managing personal ignore patterns. By understanding and using both tools appropriately, you can maintain a cleaner repository while accommodating individual development workflows.

Git Branches, Remotes, and HEAD

Yoonsoo Park — Tue, 15 Oct 2024 00:00:00 +0000

Demystify key Git concepts like local vs. remote branches, fetching, pulling, pushing, and the HEAD pointer to improve your version control skills and team collaboration.

Git Official Documentation

Demystifying Git: Understanding Branches, Remotes, and HEAD

As developers, we use Git and GitHub daily, but some concepts can still trip us up. Today, we’re going to demystify some common Git scenarios and concepts that often cause confusion. We’ll focus on the relationship between local and remote branches, the git fetch command, and the ever-mysterious HEAD.

The Tale of Two Branches: Local vs. Remote

Imagine you’re working on a feature branch called awesome-feature. You’ve created this branch locally and pushed it to GitHub. Now, both your local machine and GitHub have a branch called awesome-feature. But here’s the kicker: these two branches can diverge!

Real-life scenario:

You create awesome-feature locally and push it to GitHub.
Your colleague, Alice, pulls awesome-feature, makes some changes, and pushes to GitHub.
Now, the awesome-feature on GitHub has changes that your local awesome-feature doesn’t.

This is where the concept of “remote branches” comes in. Your local Git keeps track of the state of branches on GitHub (or any remote) using “remote-tracking branches”. These are usually named origin/branch-name.

Fetching: Updating Your Local Knowledge

When you run git fetch origin, you’re essentially asking Git to update its knowledge about the state of the remote repository. It’s like checking for new emails without actually opening them.

What `git fetch` does:

It communicates with GitHub to see what changes exist on the remote.
It updates your local remote-tracking branches (like origin/awesome-feature).
It doesn’t change your working directory or local branches.

After fetching, you can see what’s new:

1
2


git fetch origin
git diff awesome-feature origin/awesome-feature

This shows you what changes are on GitHub that you don’t have locally.

Pull: Fetch + Merge

The git pull command is actually a combination of two steps: fetch and merge. It’s like checking for new emails and automatically putting them in your inbox.

1

git pull origin awesome-feature

This fetches the latest changes from the awesome-feature branch on GitHub and merges them into your current local branch.

When you try to push your changes, Git checks if your local branch has diverged from the remote branch. If it has, you’ll get an error like:

! [rejected] awesome-feature -> awesome-feature (non-fast-forward)
error: failed to push some refs to 'https://github.com/your-repo.git'

This is Git’s way of protecting you from accidentally overwriting changes on the remote.

How to resolve:

First, pull the latest changes:
1

git pull origin awesome-feature
Resolve any merge conflicts if they occur.
Then push your changes:
1

git push origin awesome-feature

HEAD and detached HEAD

HEAD is Git’s way of knowing “where you are” in the history of your project. It’s like a bookmark in a book.

Normal HEAD:

Usually, HEAD points to the latest commit of your current branch. When you make a new commit, HEAD moves forward automatically.

HEAD -> awesome-feature -> Latest Commit

Detached HEAD:

Sometimes, you might checkout a specific commit or a remote branch directly:

1
2
3


git switch --detach abc123 # Some commit hash
# or
git switch --detach origin/awesome-feature

Now you’re in a “detached HEAD” state. It’s like you’ve placed your bookmark on a specific page, rather than at the end of a chapter.

In this state:

You can look around and make experimental changes.
If you make commits, they won’t belong to any branch.
To save your work, create a new branch:
1

git switch -c experimental-idea

Best Practices

Fetch Often: Regularly run git fetch to stay updated with remote changes.
Integrate Deliberately: Fetch, inspect the divergence, then use the repository’s merge or rebase policy. A blind pull can create an unintended merge.
Use Branches: Create feature branches for new work to keep main/master clean.

Git Diff for Pull Request Analysis

Yoonsoo Park — Mon, 30 Sep 2024 00:00:00 +0000

Learn how to streamline your pull request analysis using advanced Git diff techniques. This guide covers basic and advanced methods to focus on relevant code changes and improve your review process.

Git Documentation

Git Diff for Pull Request Analysis

As a developer, reviewing pull requests is a crucial part of the software development process. While platforms like GitHub and GitLab offer user-friendly interfaces for this task, sometimes we need a more tailored approach. This guide will show you how to leverage the power of git diff to analyze pull requests effectively and efficiently.

Understanding the Basics of Git Diff

Before diving into advanced techniques, let’s cover the fundamental git diff commands for pull request analysis:

Ensure you’re on the target branch (usually main):
1

git switch main
Fetch the latest changes:
1

git fetch origin
View changes between the current branch and the pull request branch:
1

git diff origin/main...origin/feature-branch
1. e.g. origin/release is the target branch, and story/DX-16597 is the pull request branch.
  1
  
  git diff origin/release...origin/story/DX-16597

For a concise summary of changes:

1

git diff --stat origin/main...origin/feature-branch

To see only changed file names:

1

git diff --name-status origin/main...origin/feature-branch

These commands provide a solid foundation for pull request analysis, but they often include more information than necessary.

Advanced Git Diff Techniques for Focused Analysis

To overcome the limitations of standard git diff output, which often includes irrelevant files like CHANGELOG.md or package-lock.json, we can use a more refined approach:

1
2
3
4
5
6
7
8
9


git fetch origin
git diff origin/main...origin/feature-branch \
 --unified=0 \
 ':!CHANGELOG.md' \
 ':!package-lock.json' \
 ':!yarn.lock' \
 ':!*.lock' \
 ':!*.md' \
 > pr_changes.txt

This command:

Fetches the latest changes
Compares the main branch to the feature branch
Shows only changed lines without context
Excludes specific files and file types
Outputs the result to a file

Review note: path exclusions should be deliberate. Lockfiles, migrations, documentation, and generated metadata can be security- or behavior-relevant and should not be hidden by default. Unmatched exclude pathspecs do not require deleting the pattern in normal modern Git usage.

Customizing Your Git Diff Approach

Pathspecs make the command adaptable, but every exclusion narrows the review evidence. You can easily modify the exclusion patterns to suit your project’s needs. For example, to exclude all JSON files, add :!*.json to the list.

Implementing the Advanced Git Diff Technique

After running the advanced command, you’ll have a pr_changes.txt file containing a focused diff of your pull request. You can:

Review the changes directly in this file
Share the file with team members for collaborative review
Use the content with AI tools for automated analysis without context limit concerns

For a quick overview, use:

1

head -n 50 pr_changes.txt

This displays the first 50 lines of the diff, giving you a snapshot of the changes.

Conclusion

Compare from the merge base, keep review-relevant files visible, and use the hosting platform’s PR diff as a second view before approval.

Useful VS Code Shortcuts for Everyday Editing

Yoonsoo Park — Sat, 21 Sep 2024 00:00:00 +0000

This reference lists common bindings; verify each one in the Keyboard Shortcuts editor for your operating system and keymap.

Visual Studio Code Keyboard Shortcuts Reference

As developers, we’re always obsessed with ways to streamline our workflow and boost productivity. Visual Studio Code (VS Code) offers numerous shortcuts to help us code more efficiently. In this article, we’ll explore some cool VS Code shortcuts that can significantly improve your coding experience.

Quick Reference Table

Bindings vary by operating system, keymap extension, and user configuration. Use VS Code’s Keyboard Shortcuts editor as the source of truth and inspect conflicts before changing a binding.

Function	Mac	Windows/Linux
Jump to Matching Bracket	Cmd + Shift + \	Ctrl + Shift + \
Scroll Without Moving Cursor	Ctrl + Fn + Up/Down Arrow	Ctrl + Up/Down Arrow
Show/Hide Terminal	Cmd + J	Ctrl + J
Expand/Shrink Selection	Ctrl + Shift + Left/Right Arrow	Shift + Alt + Left/Right Arrow
Change Tab	Cmd + Opt + Left/Right Arrow	Ctrl + PgUp/PgDn
Find Symbol	Cmd + T	Ctrl + T
Multi-Cursor (select next occurrence)	Cmd + D	Ctrl + D
Multi-Cursor (add above/below)	Cmd + Option + Up/Down Arrow	Ctrl + Alt + Up/Down Arrow
Quick File Navigation	Cmd + P	Ctrl + P
Toggle Line Comment	Cmd + /	Ctrl + /
Rename Symbol	F2	F2
Open Command Palette	Cmd + Shift + P	Ctrl + Shift + P

Detailed Explanations

Jump to Matching Bracket
- Mac: Cmd + Shift + \
- Windows/Linux: Ctrl + Shift + \
Quickly navigate between opening and closing brackets in nested code structures.

Jump Multiple Lines Vertically (Custom shortcut)

Requires configuration in keybindings.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20


{
 "key": "ctrl+up",
 "command": "cursorMove",
 "args": {
 "to": "up",
 "by": "line",
 "value": 10
 },
 "when": "editorTextFocus"
},
{
 "key": "ctrl+down",
 "command": "cursorMove",
 "args": {
 "to": "down",
 "by": "line",
 "value": 10
 },
 "when": "editorTextFocus"
},

Move the cursor 10 lines up or down at once for faster navigation in large files.

Scroll Without Moving the Cursor
- Mac: Ctrl + Fn + Up Arrow / Down Arrow
- Windows/Linux: Ctrl + Up Arrow / Down Arrow
Scroll through your code while keeping your cursor in the same position.
Show/Hide Terminal
- Mac: Cmd + J
- Windows/Linux: Ctrl + J
Quickly toggle the integrated terminal for running commands.
Expand/Shrink Selection
- Mac: Ctrl + Shift + Left Arrow / Right Arrow
- Windows/Linux: Shift + Alt + Left Arrow / Right Arrow
Expand or shrink your selection based on code structure.
Change Tab
- Mac: Cmd + Opt + Left / Right Arrow
- Windows/Linux: Ctrl + PgUp / PgDn
Quickly switch between open tabs in your editor.
Find Symbol
- Mac: Cmd + T
- Windows/Linux: Ctrl + T
Find classes, functions, or properties anywhere in your current editor session with fuzzy search.
Multi-Cursor Editing
- Select next occurrence:
  - Mac: Cmd + D
  - Windows/Linux: Ctrl + D
- Add cursor above/below:
  - Mac: Cmd + Option + Up Arrow / Down Arrow
  - Windows/Linux: Ctrl + Alt + Up Arrow / Down Arrow
Edit multiple occurrences of text simultaneously.
Quick File Navigation
- Mac: Cmd + P
- Windows/Linux: Ctrl + P
Open files in your project by typing part of the file name.
Toggle Line Comment
- Mac: Cmd + /
- Windows/Linux: Ctrl + /
Quickly comment or uncomment lines of code.
Rename Symbol
- Mac/Windows/Linux: F2
Rename variables, functions, or classes across your entire project.
Open Command Palette
- Mac: Cmd + Shift + P
- Windows/Linux: Ctrl + Shift + P
Access all of VS Code’s commands quickly.

Use the shortcuts that remove friction from repeated work. There is no benefit in memorizing bindings that do not fit the way you edit or that conflict with accessibility needs.

Package and Install a Python Command-Line Application

Yoonsoo Park — Sat, 14 Sep 2024 00:00:00 +0000

A shebang, executable bit, and symlink can expose one local script, but they do not describe dependencies, create an isolated environment, support Windows, or provide a reliable upgrade and uninstall path. A maintained CLI should be packaged as a Python application and installed in an isolated environment.

This guide was verified on 2026-08-01 against the PyPA guides for creating command-line tools and installing standalone command-line tools, plus the entry-points specification.

Project layout

1
2
3
4
5
6
7
8


code-collector/
├── pyproject.toml
├── src/
│ └── code_collector/
│ ├── __init__.py
│ └── cli.py
└── tests/
 └── test_cli.py

Keep command behavior in a callable function. Return an exit code instead of calling sys.exit deep inside business logic.

1
2
3
4
5
6
7
8
9


# src/code_collector/cli.py
import argparse

def main() -> int:
 parser = argparse.ArgumentParser()
 parser.add_argument("path")
 args = parser.parse_args()
 print(args.path)
 return 0

Declare the command

One standards-based pyproject.toml example using Hatchling is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "code-collector"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = []

[project.scripts]
code-collector = "code_collector.cli:main"

The [project.scripts] entry creates a platform-appropriate launcher. The same package can work on macOS, Linux, and Windows without asking users to create symlinks manually. Select and pin a maintained build backend according to repository policy; Hatchling is an example, not a universal requirement.

Develop and test safely

1
2
3
4
5
6


python3 -m venv .venv
source .venv/bin/activate
python -m pip install --editable .
code-collector --help
python -m pytest
python -m build

An editable install is useful during development because source changes are visible without reinstalling. Build both wheel and source distribution before release, inspect their contents, and test the wheel in a fresh environment. Avoid importing or executing project code from build configuration.

Install as an application

For a local or published CLI, pipx gives each application its own virtual environment while exposing its commands on PATH:

1
2
3
4


pipx install .
code-collector --help
pipx upgrade code-collector
pipx uninstall code-collector

Users can install from an approved package index or an explicitly trusted source. Do not encourage installation from an unreviewed URL, and never embed index credentials in documentation or repository files.

Alternatives and tradeoffs

A shell alias is adequate for a personal one-line convenience command, but is not a distributable application.
A repository-local script can be run as python path/to/script.py; this is simple when only contributors use it.
A zipapp can distribute some pure-Python applications as one archive, but dependency and native-extension constraints require care.
Tools such as Typer or Click provide richer CLI ergonomics; argparse avoids an external runtime dependency.
Native launchers or standalone bundlers can remove the requirement for a user-managed Python, at the cost of larger artifacts and platform-specific builds.

Migration checklist

Identify the current command name, arguments, exit codes, configuration, and dependencies.
Move behavior into an importable package and a small main function.
Add pyproject.toml metadata and a console entry point.
Add tests for help, invalid input, normal output, and nonzero failures.
Install the wheel in a clean environment on every supported platform.
Document pipx install, upgrade, and uninstall commands.
Remove the old symlink only after command -v code-collector resolves to the packaged launcher and acceptance tests pass.

Verification gate

Record the verification date and run:

1
2
3
4


python -m build
python -m pip install --force-reinstall dist/*.whl
code-collector --help
python -m pytest

Also verify signal handling, filesystem permissions, encoding, and exit status for the environments the CLI actually supports.

Release and maintenance

Build releases from a tagged, clean commit and publish immutable versioned artifacts. When publishing to PyPI from CI, use trusted publishing where available instead of storing a long-lived token. Generate provenance evidence when the distribution context requires it.

Treat stdout and stderr as interfaces. Keep machine-readable output stable or versioned, send diagnostics to stderr, and document exit codes. Avoid update checks or telemetry that delay startup or violate user expectations. When dropping a Python version, moving configuration, or renaming an option, publish a migration note and test the old failure path so users receive an actionable message. Assign ownership for dependency updates, supported platforms, vulnerability response, and retirement of obsolete releases.

Python Package Updates - A Guide to Updating and Verifying Your Packages

Yoonsoo Park — Thu, 22 Aug 2024 00:00:00 +0000

Learn how to keep your Python packages up-to-date and verify their versions for secure and efficient development.

Python Package Index (PyPI)

Updating and Verifying Python Packages

In the fast-paced world of Python development, staying up-to-date with your packages is crucial for maintaining secure, efficient, and bug-free applications. This guide will walk you through the essential steps of updating your Python packages and verifying their versions, ensuring you’re always working with the latest and greatest tools.

Updating Python Packages

Work in an isolated environment and update the project declaration or lock workflow, not merely the installed environment. Review release notes, resolve a small scope, and run the full test and build gates before merging.

Once you’ve installed a Python package using pip, you might wonder how to keep it current. The process is straightforward:

Open your terminal or command prompt.
Use the following command to update a package:
```
pip install --upgrade package_name
```
Replace package_name with the name of the package you want to update.

For example, to update a package called “requests”, you would run:

python -m pip install --upgrade requests

This command fetches the latest version of the package from the Python Package Index (PyPI) and installs it, replacing the older version.

Verifying Package Versions

After updating, it’s a good practice to verify that you’re running the latest version. Here’s how you can do that:

1. Check the Installed Version

To see the currently installed version of a package, use the pip show command:

python -m pip show package_name

This displays information about the package, including its version number.

2. Check the Latest Available Version

To see all available versions of a package, including the latest, use:

python -m pip index versions package_name

The output will show all available versions, with the most recent typically at the top.

3. Compare Versions

Compare the installed version (from step 1) with the latest available version (from step 2) to ensure you’re up-to-date.

4. Automated Check for Outdated Packages

For a quick overview of all installed packages that have updates available, use:

python -m pip list --outdated

This command displays a list of packages with newer versions available, showing both the current and latest versions.

Best Practices

Regularly update your packages to benefit from bug fixes, security patches, and new features.
Before updating packages in a production environment, test the updates in a development or staging environment to ensure compatibility.
Use virtual environments to isolate project dependencies and avoid conflicts between different projects.
- Setting Up Virtual Environments for Multiple Python Versions
Keep an eye on the changelogs or release notes of critical packages to understand what’s new in each update.

How to Ignore Files Locally in Git Without Modifying .gitignore

Yoonsoo Park — Sun, 18 Aug 2024 00:00:00 +0000

Learn how to use .git/info/exclude to ignore files locally in Git without affecting the shared .gitignore file

Git Documentation

Have you ever needed to ignore certain files or directories in your Git project, but didn’t want to modify the shared .gitignore file? Perhaps you have some local development files or personal IDE settings that you don’t want to track, but also don’t want to burden your team with. There’s a simple solution for this: the .git/info/exclude file.

Using .git/info/exclude

The .git/info/exclude file works just like .gitignore, but it’s not tracked by Git. This means you can add custom ignore rules that apply only to your local repository without affecting other team members or the remote repository.

Here’s how to use it:

Navigate to your project’s root directory.
Open the .git/info/exclude file in your favorite text editor. If it doesn’t exist, create it.
Add your custom ignore rules to this file, one per line.

For example, you might add:

# Ignore local development environment file
.env.local
# Ignore personal IDE settings
.vscode/
# Ignore a specific local directory
local_scripts/

These rules will apply only to your local repository and won’t be committed or pushed to the remote repository.

Benefits of Using .git/info/exclude

Keeps your personal ignore rules separate from the project’s shared rules.
Avoids cluttering the shared .gitignore file with personal preferences.
Prevents conflicts that might arise from different team members having different ignore needs.

When to Use .gitignore vs .git/info/exclude

Use .gitignore for ignore rules that should apply to all copies of the repository.
Use .git/info/exclude for personal ignore rules that are specific to your local setup.

By leveraging .git/info/exclude, you can maintain a clean and personalized local Git environment without affecting your team’s workflow. It’s a simple yet powerful feature that every Git user should know about.

Evidence-Driven AI-Assisted Software Development

Yoonsoo Park — Mon, 12 Aug 2024 00:00:00 +0000

Telling a model “act as a project manager, architect, then senior engineer” can improve presentation, but roles do not make its claims correct. Modern coding agents can inspect repositories, edit files, run commands, and use external tools. The useful unit of control is therefore not a persona. It is a bounded task with observable evidence and an approval boundary.

The current mental model

Treat the agent as an untrusted but capable collaborator operating inside a defined workspace. Give it the minimum context and tools needed for one outcome. Require it to distinguish repository facts, current external facts, assumptions, and user decisions. Let deterministic tools verify what they can; reserve human review for intent, architecture, security, and product judgment.

A practical loop is:

Orient: read repository instructions, current implementation, tests, ownership boundaries, and dirty-worktree state.
Specify: state the goal, non-goals, acceptance tests, risk, data sensitivity, and rollback.
Plan: identify interfaces and impacted behavior before editing.
Change narrowly: use small diffs with clear file ownership; preserve unrelated work.
Validate: run formatting checks, type checks, unit/integration tests, builds, security checks, and targeted manual scenarios.
Review evidence: inspect the diff and actual test output; challenge unsupported claims.
Release gradually: use a branch, preview, feature flag, canary, or reversible migration proportional to risk.
Learn: capture only durable project-specific gotchas, not raw private conversation.

A task brief that is more useful than a role prompt

1
2
3
4
5
6
7
8
9


Goal: Reject uploads larger than 10 MB before processing.
In scope: API validation, error response, tests, docs.
Out of scope: Storage migration and UI redesign.
Constraints: Preserve current API shape; do not log filenames or content.
Acceptance:
- 10 MB succeeds; 10 MB + 1 byte returns 413.
- Existing auth behavior is unchanged.
- Unit and integration suites pass.
Evidence required: changed-file list, test commands/results, remaining manual gate.

The agent should first verify where upload limits are currently enforced. It should not invent a framework, environment, or production result. If a current library API or cloud feature matters, consult primary documentation and record the verification date.

Security and privacy boundaries

Repository text, issue content, retrieved web pages, and tool output can contain prompt injection. Treat them as data, not authority. Keep high-impact tools deny-by-default, review commands that publish, delete, deploy, or access secrets, and separate read-only discovery from mutation.

Do not send customer data, credentials, private source, or meeting transcripts to a model unless the approved service and data policy permit it. Redact fixtures and logs. Ensure generated dependencies, licenses, network calls, and telemetry match organizational policy. An agent must never claim a production or device validation that only ran against a local fixture.

Evaluation and testing

Compile/build success is necessary but not sufficient. Use a layered gate:

static checks for syntax, types, formatting, policy and secret scanning;
deterministic tests for contracts and regression cases;
integration tests at real boundaries using controlled environments;
security tests for authorization, injection, data exposure, and failure handling;
fresh-context human acceptance for usability and ambiguous requirements.

For repeated AI tasks, maintain an evaluation set with representative requests, expected properties, prohibited behavior, and cost/latency measurements. Do not optimize a prompt on one anecdote. Compare versions and preserve failures as regression cases where privacy permits.

Tradeoffs

Agents can accelerate discovery, repetitive edits, tests, and documentation, but larger autonomous changes increase review burden and correlated mistakes. Parallel agents help when file ownership and output contracts are disjoint; otherwise they create merge conflicts and inconsistent decisions. More context can improve local fit but also increases privacy exposure and distracts the model. The smallest sufficient context is usually better.

Migration checklist

Replace reusable persona prompts with task briefs and acceptance evidence.
Add repository instructions for validation, secrets, ownership, and release.
Inventory tool permissions and require approval for irreversible/external actions.
Split large work into independently reviewable changes.
Establish deterministic tests and a small evaluation suite before scaling usage.
Record current-source citations for unstable technical claims.
Require diff review, rollback notes, and an explicit list of unverified gates.
Measure escaped defects and review time, not generated lines of code.

Verified on 2026-08-01.

Primary sources

Efficiently Read a Git Repository from AWS Lambda

Yoonsoo Park — Wed, 31 Jul 2024 00:00:00 +0000

AWS Lambda still has a 15-minute execution limit, but /tmp is no longer fixed at 512 MB. Ephemeral storage is configurable from 512 MB to 10,240 MB. More space can make a job fit, but it does not fix unbounded clone time, unsafe credentials, concurrent capacity, or a workflow that needs to run longer than Lambda allows.

Pick the lightest retrieval method

If you need files from one immutable commit or tag and do not need Git history, download a GitHub archive or use the Contents API. This avoids shipping a Git binary and object database in the Lambda package.

If you need Git semantics, combine three distinct controls:

shallow fetch limits commit history;
partial clone/filter avoids downloading unneeded object contents when the server supports it;
sparse checkout limits which paths appear in the working tree.

Sparse checkout alone does not guarantee a small network transfer because objects outside the working tree may already have been fetched.

1
2
3
4


git clone --depth=1 --filter=blob:none --sparse \
 --branch v1.2.3 https://github.com/example/project.git /tmp/project
git -C /tmp/project sparse-checkout set --cone src config.json
git -C /tmp/project rev-parse --verify 'HEAD^{commit}'

Treat a tag, branch, repository URL, and sparse path received from an event as untrusted. Prefer a full commit SHA from an allowlisted repository. Do not build a shell string from those values. In Python, call a subprocess with an argument array, set a timeout, capture bounded output, and clean a unique invocation directory in finally.

Authentication

For a private GitHub repository, prefer a GitHub App installation token with narrow repository permissions and short lifetime. Store the app private key in an approved secret store and never put a token in the clone URL, where logs and errors can reveal it. Configure a credential helper or an HTTP authorization header without logging it. A personal access token tied to one developer has weaker ownership and rotation characteristics.

Lambda’s AWS execution role and GitHub identity solve different boundaries. Scope the execution role to required secrets, S3, logs, or other AWS actions.

Storage and packaging

Set ephemeral storage from measured repository and concurrency needs, not the maximum by default. /tmp is isolated per execution environment and can survive warm reuse, so use unique directories and never trust leftovers from a previous invocation. Encrypting temporary storage is handled by Lambda, but the data still belongs in the threat model and retention design.

Git is not included in every Lambda runtime. Package a pinned Git build in a Lambda layer or container image and scan/update it. Verify architecture compatibility. Container image size and cold starts may make an archive/API approach simpler.

When Lambda is the wrong runtime

Use Step Functions to coordinate bounded Lambda steps, AWS Batch or ECS/Fargate for long or resource-heavy repository analysis, or CodeBuild when the workload is fundamentally a build. Move away from Lambda when worst-case input approaches 15 minutes, needs large durable workspaces, or invokes many untrusted repository hooks/tools.

Verification checklist

Measure transfer, disk use, cold-start and runtime against the largest allowed repository.
Test invalid and moved tags, annotated tags, missing sparse paths, timeout, rate limit, and partial-clone fallback.
Verify commit SHA before analysis and reject unapproved repository hosts.
Confirm tokens are absent from logs, exceptions, process arguments, and telemetry.
Clean /tmp and cap subprocess time/output.
Test duplicate events and make downstream writes idempotent.

Official documentation reviewed on 2026-08-01:

Resolving 'No Default Dev Hub' Error When Creating Salesforce Scratch Orgs

Yoonsoo Park — Tue, 16 Jul 2024 00:00:00 +0000

Learn how to fix the ‘No Default Dev Hub’ error when creating Salesforce scratch orgs using Salesforce CLI, with step-by-step solutions and explanations.

Salesforce Developer Documentation

As a Salesforce developer, you’re likely familiar with the power and flexibility of scratch orgs for development and testing. However, you may occasionally encounter errors when trying to create these temporary environments. One common issue is the “No Default Dev Hub” error, which can be frustrating if you’re not sure how to resolve it. In this article, we’ll explore this error and provide two straightforward solutions to get you back on track.

The Problem: No Default Dev Hub Error

Let’s say you’re trying to create a scratch org using the Salesforce CLI with a command like this:

1

sf org create scratch --definition-file=config/project-scratch-def.json --alias=my-scratch --set-default --duration-days=30 --wait=15

But instead of creating your scratch org, you’re met with this error:

Error (NoDefaultDevHubError): No default dev hub found. Use -v or --target-dev-hub to specify an environment.

This error occurs when the Salesforce CLI can’t find a default DevHub to use for creating your scratch org. Even if you have a DevHub set up and can see it when you run sf org list, the CLI may not know which one to use by default.

Solution 1: Set a Default DevHub

The first and most straightforward solution is to set a default DevHub for your Salesforce CLI to use. Here’s how:

First, identify your DevHub username. You can find this by running sf org list. Look for the org with the “DevHub” type.
Once you have the username, set it as the default DevHub with this command:
1

sf config set target-dev-hub your-devhub-username@example.com
Replace your-devhub-username@example.com with your actual DevHub username.
After setting the default, you should be able to run your original scratch org creation command without any issues.

This method is particularly useful if you primarily work with one DevHub, as you won’t need to specify it every time you create a scratch org.

Solution 2: Specify the DevHub in Your Command

If you work with multiple DevHubs or prefer not to set a default, you can explicitly specify which DevHub to use in your scratch org creation command. Here’s how:

Modify your original command to include the -v or --target-dev-hub flag, followed by your DevHub username:

1

sf org create scratch --definition-file=config/project-scratch-def.json --alias=my-scratch --set-default --duration-days=30 --wait=15 --target-dev-hub your-devhub-username@example.com

Again, replace your-devhub-username@example.com with your actual DevHub username.

Run this modified command, and it should create your scratch org without the “No Default Dev Hub” error.

This method gives you more flexibility if you need to switch between different DevHubs for various projects or teams.

Verification and CI guidance

Run sf org display --target-org my-scratch and confirm the org ID, expiration, and intended Dev Hub. Project-local target-dev-hub is convenient for developers; an explicit --target-dev-hub is safer in CI because it does not depend on ambient configuration. Verified against the scratch org guide on 2026-08-01.

The “No Default Dev Hub” error is a common hurdle in Salesforce development, but it’s easily overcome with these simple solutions. Whether you choose to set a default DevHub or specify it in each command, you’ll be able to create scratch orgs smoothly and continue your development work without interruption.

Cheers! 🍺

Why `forEach` Cannot Handle Async - A Real-Life Example and Solutions

Yoonsoo Park — Sat, 22 Jun 2024 00:00:00 +0000

In JavaScript, handling asynchronous operations can be tricky, especially when dealing with collections of data. One common pitfall is using the forEach method for asynchronous tasks. This article explains why forEach cannot handle async operations properly and presents solutions using for...of loops or the map method combined with Promise.all.

The Problem with `forEach` and Async

The forEach method is great for iterating over arrays, but it doesn’t handle asynchronous operations as you might expect. When you use forEach with an async function, it does not wait for the promises to resolve before moving on to the next iteration. This can lead to unexpected behavior and incomplete operations.

Real-Life Example: Uploading Files

Imagine you are building a file upload feature that processes and uploads multiple files to a server. You might think using forEach with an async function is a good approach. Let’s see what happens when you do this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


async function uploadFiles(filePaths) {
 filePaths.forEach(async (filePath) => {
 const fileContent = await readFile(filePath); // Assume readFile is a function that reads file content
 await uploadToServer(fileContent); // Assume uploadToServer is a function that uploads the file content
 console.log(`Uploaded ${filePath}`);
 });
 console.log("All files uploaded");
}

const files = ["file1.txt", "file2.txt", "file3.txt"];
uploadFiles(files);

You might expect to see log messages for each file upload followed by “All files uploaded”, but instead, you’ll likely see “All files uploaded” before any individual file upload messages. (surprise!) This happens because forEach does not wait for the async operations to complete.

Solution 1: Using `for...of` Loop

A more reliable way to handle asynchronous operations in a loop is using the for...of statement. This approach ensures that each iteration waits for the async operations to finish before moving on to the next one.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


async function uploadFiles(filePaths) {
 for (const filePath of filePaths) {
 const fileContent = await readFile(filePath); // Assume readFile is a function that reads file content
 await uploadToServer(fileContent); // Assume uploadToServer is a function that uploads the file content
 console.log(`Uploaded ${filePath}`);
 }
 console.log("All files uploaded");
}

const files = ["file1.txt", "file2.txt", "file3.txt"];
uploadFiles(files);

With this approach, you will see each file upload log message in sequence, followed by “All files uploaded” at the end, as expected.

Solution 2: Using `map` with `Promise.all`

Promise.all is fail-fast and starts all mapped operations immediately. Use Promise.allSettled when every result must be collected, or a maintained concurrency limiter when the input can exhaust sockets, memory, or service quotas.

Another solution is to use the map method to create an array of promises and then wait for all of them to resolve using Promise.all. This approach is useful when you want to perform async operations in parallel.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


async function uploadFiles(filePaths) {
 const uploadPromises = filePaths.map(async (filePath) => {
 const fileContent = await readFile(filePath); // Assume readFile is a function that reads file content
 await uploadToServer(fileContent); // Assume uploadToServer is a function that uploads the file content
 console.log(`Uploaded ${filePath}`);
 });

 await Promise.all(uploadPromises);
 console.log("All files uploaded");
}

const files = ["file1.txt", "file2.txt", "file3.txt"];
uploadFiles(files);

This code will log the upload messages for each file, potentially out of order, but “All files uploaded” will be logged only after all files have been processed.

Conclusion

Handling asynchronous operations in JavaScript requires careful consideration, especially when dealing with loops. The forEach method is not suitable for async tasks because it does not wait for promises to resolve. Instead, use for...of loops to handle async operations sequentially or map with Promise.all to handle them in parallel.

Choose sequential, unbounded parallel, settled-result, or bounded-concurrency execution from the operation’s ordering, error, and resource requirements.

Salesforce CI/CD with AWS CodePipeline and CodeBuild

Yoonsoo Park — Sat, 15 Jun 2024 00:00:00 +0000

Verified against AWS and Salesforce documentation on 2026-08-01.

Why the old architecture was archived

AWS CodeDeploy deploys applications to AWS compute targets; it is not a Salesforce metadata deployment engine. A Salesforce source tree also doesn’t become a deployable “package” merely by converting it and putting the directory in S3. The archived pipeline mixed invalid CloudFormation, deprecated sfdx commands, an unnecessary plugin install, and no credible authentication or rollback boundary.

Use AWS only when the organization already operates CodePipeline/CodeBuild or needs its account controls. GitHub Actions, Salesforce DevOps Center, or another CI platform can be simpler. The important design is the release gate, not the vendor running the shell.

Supported pipeline

Source: AWS CodeConnections delivers the reviewed Git revision to CodePipeline. Restrict the connection to the repository and branch required by the pipeline.
Validation: CodeBuild uses a pinned image with the supported sf CLI, authenticates without printing credentials, and runs tests plus sf project deploy start --dry-run.
Evidence: Store the commit, CLI version, target, component set, test results, and validation/deploy ID as build evidence. Do not store auth URLs, tokens, private keys, or customer data.
Approval: A production stage requires an explicit manual approval after validation. The approver checks the exact commit and target org.
Deploy: A separate CodeBuild action deploys the same immutable revision. When Salesforce permits quick deploy for the validated result, use the validation/deploy ID; otherwise run the same scoped deployment again.
Verify: Run smoke tests and check the deployment result and application behavior.

CodeDeploy isn’t in this flow. Lambda is unnecessary unless orchestration requires a narrowly defined custom action that CodeBuild can’t perform.

Authentication boundary

CodeBuild’s AWS role should receive only the AWS permissions needed for source artifacts, logs, and a specific secret. Store Salesforce authentication material in AWS Secrets Manager and inject it only into the build that needs it. Prefer an approved workload/OIDC federation when the Salesforce and CI design supports it. Otherwise, use a dedicated least-privileged integration user and a supported noninteractive OAuth flow such as JWT bearer authentication, protecting and rotating the private key.

Never bake a token or key into the image, repository, buildspec, environment-variable declaration, or artifact. Disable shell tracing around authentication. A Salesforce SFDX auth URL is a credential too.

Validation build

Pin the CLI version in the image or dependency lock and print only its version:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


version: 0.2
phases:
 install:
 commands:
 - sf version
 pre_build:
 commands:
 - ./scripts/authenticate-salesforce-from-secret
 - python3 scripts/validate_frontmatter.py
 build:
 commands:
 - sf project deploy preview --manifest manifest/package.xml --target-org prod
 - sf project deploy start --manifest manifest/package.xml --target-org prod --dry-run --test-level RunLocalTests --wait 60 --json > deploy-validation.json
artifacts:
 files:
 - deploy-validation.json

The authentication helper must read the secret without echoing it, authorize the explicit alias, and remove temporary key material on exit. Add project-specific static analysis and unit tests before validation. Fail the build on any test, component, or JSON status failure; don’t rely only on the shell command producing a file.

Deployment, rollback, and tradeoffs

Quick deploy reduces repeated test time but is valid only within Salesforce’s permitted window and for the exact successful validation. Preserve its ID with the immutable commit. If it is unavailable, deploy the same manifest and commit normally.

Metadata deployment is not a universal rollback system. Prepare a forward fix or a previously tested reverse deployment. Destructive changes, irreversible data migrations, package version promotion, and permission changes need separate gates and recovery plans. Keep data migration outside the metadata action and make it idempotent.

CodePipeline provides AWS-native approvals and account audit trails, but CodeBuild startup and cross-cloud authentication add complexity. DevOps Center offers Salesforce-native workflows. GitHub Actions can reduce infrastructure when the source already lives on GitHub. Choose the platform the team can secure and operate; preserve the same validation, approval, identity, and rollback controls.

Migration checklist

Remove CodeDeploy, legacy sfdx force:*, and generated S3 “package” assumptions.
Establish CodeConnections with least repository access and an explicit trigger.
Pin sf, the build image, and project dependencies.
Create a least-privileged Salesforce integration identity and Secrets Manager boundary.
Separate validation and production deploy actions around manual approval.
Prove the same commit, manifest, target org, and validation ID cross the gate.
Test authentication failure, Apex failure, timeout, approval rejection, stale quick-deploy ID, and rollback.
Add post-deploy smoke checks and alerts without exposing Salesforce payloads.

Official sources

Use Salesforce Record Types Without Hard-Coded IDs

Yoonsoo Park — Tue, 04 Jun 2024 00:00:00 +0000

Verified against Salesforce documentation on 2026-08-01.

Why the old example was archived

Record Type IDs differ between orgs, so a map containing 012... values isn’t portable. The earlier Business Account versus Individual Account example also implied that an ordinary Account record type turns an Account into a person. Salesforce Person Accounts are a distinct feature and data model combining Account and Contact behavior; enabling them is an organizational decision, not a record-type label.

Decide whether a record type is needed

Use a record type when one object supports materially different business processes, picklist value sets, or page-layout experiences. Don’t add one for a conditional field, security boundary, or reporting label. Dynamic Forms can handle presentation; permission sets handle access; a picklist may be enough for classification.

For Accounts, decide first whether the business manages organizations only or requires Person Accounts. Confirm edition, feature implications, integrations, sharing, duplicate management, and reporting before enabling Person Accounts. Don’t simulate a person with a custom “Individual Account” record type unless that is an intentional custom model.

Resolve IDs in each org

In Apex, use describe metadata rather than SOQL or a hard-coded ID:

Schema.RecordTypeInfo info = Account.SObjectType
.getDescribe()
.getRecordTypeInfosByDeveloperName()
.get('Business_Account');
if (info == null || !info.isAvailable()) {
throw new IllegalArgumentException('Business_Account is unavailable');
}
Id businessRecordTypeId = info.getRecordTypeId();

Check isAvailable() because profile and permission assignments affect what the current user can use. In integration preprocessing, query by SObjectType and DeveloperName in the target org, cache only for that run, and fail if the result is absent or ambiguous:

1
2
3
4


sf data query --target-org staging --use-tooling-api --query \
 "SELECT Id, DeveloperName, Name, IsActive
 FROM RecordType
 WHERE SObjectType = 'Account' AND DeveloperName = 'Business_Account'"

Safe import and upsert

CSV tools generally need the resolved RecordTypeId, not a relationship column invented by the client. Keep RecordTypeDeveloperName in the source export, resolve it against the target org, produce a temporary transformed CSV, and inspect unmapped values before loading.

1
2


External_Id__c,Name,RecordTypeDeveloperName
ORG-100,Acme Corp,Business_Account

Load with a stable external ID only after transformation:

1
2


sf data upsert bulk --target-org staging --sobject Account \
 --file accounts-resolved.csv --external-id External_Id__c --wait 10

Never copy RecordTypeIds or record IDs between environments. Protect input files containing customer data and reconcile successful, failed, and unprocessed results.

Tradeoffs and migration checklist

Record types give administrators a supported process boundary but multiply layouts, assignments, tests, and migration mappings. A single record type is simpler where behavior doesn’t truly diverge.

Inventory record types by object, developer name, purpose, assignments, and active use.
Separate real business-process differences from UI, access, and reporting concerns.
Decide explicitly whether Person Accounts are part of the model.
Replace hard-coded IDs with describe or target-org lookup.
Assign record types through profiles or permission sets and test least-privileged personas.
Transform a small synthetic CSV, validate mapping counts, and upsert into a sandbox.
Test create, edit, automation, integrations, duplicate rules, and reports for every supported type.
Monitor failures after release and retain a rollback mapping.

Official sources

Choose the Right Salesforce API

Yoonsoo Park — Sun, 05 May 2024 00:00:00 +0000

Verified on 2026-08-01.

Why the old guide changed

Metadata, Tooling, and Bulk aren’t interchangeable sizes of one API. They address configuration, developer tooling, and high-volume data. A useful chooser must also include REST, SOAP, Composite, GraphQL, and UI API.

Decision matrix

Need	Start with	Reason
CRUD/query business records	REST API	Direct synchronous resource model
Several dependent REST operations	Composite API	Fewer round trips and optional transactional grouping
Large asynchronous ingest/extract	Bulk API 2.0	Job-based CSV processing and partial-result handling
Deploy/retrieve configuration	Metadata API	Metadata lifecycle and package manifests
Tests, traces, coverage, dev artifacts	Tooling API	Developer-tool objects
Flexible graph-shaped reads	GraphQL API	Client-selected related fields
Salesforce-shaped UI data	UI API	Layout, metadata, data, and user context
Existing enterprise WSDL contract	SOAP API	Strong generated contract and mature integrations

Choose first by resource: records, metadata, tooling, or UI. Then consider volume, latency, transaction boundaries, supported objects, API version, limits, and client capability.

Safe examples

For a small synchronous query, use REST through the authenticated CLI without exposing a token:

1
2


sf data query --target-org integration-test \
 --query "SELECT Id, Name FROM Account ORDER BY CreatedDate DESC LIMIT 10" --json

For a large CSV upsert, use Bulk API 2.0 and reconcile every result category:

1
2


sf data upsert bulk --target-org integration-test \
 --sobject Account --file accounts.csv --external-id External_Id__c --wait 10

Use OAuth with least scopes, an External Client App for new Salesforce OAuth integrations where applicable, TLS, secret rotation, timeouts, idempotency keys or stable external IDs, bounded retries, and structured logs without payloads or credentials.

Tradeoffs

REST is simple but chatty. Composite reduces calls but creates larger failure surfaces. GraphQL avoids over-fetching but isn’t a replacement for every mutation or metadata operation. UI API respects Salesforce UI semantics but couples clients to that model. Bulk API 2.0 scales but is asynchronous and can partially succeed. SOAP provides a rigid contract at the cost of XML and generated-client complexity.

Migration checklist

Inventory endpoints by resource, call volume, latency, and failure semantics.
Remove claims that Bulk API is for reporting or Tooling API is a general refactoring engine.
Move large record jobs to Bulk API 2.0 only when asynchronous partial results are acceptable.
Keep configuration delivery on Metadata API and developer observations on documented Tooling objects.
Pin an API version and test the next version before upgrading.
Add limit, timeout, retry, duplicate, permission, and partial-failure tests.
Verify record counts, metadata component sets, and final business state—not only HTTP success.

Official sources

Leveraging NPX and NVM for Efficient Backend Development

Yoonsoo Park — Tue, 30 Apr 2024 00:00:00 +0000

NVM selects a Node.js runtime, while NPX or npm exec runs a package command. They solve separate concerns and should be pinned according to the project policy.

Understanding NPX and NVM

Use a supported Node.js LTS pinned by the project. Prefer installed project scripts or npm exec --package=name -- command with an explicit reviewed version; allowing NPX to download an unpinned package adds a supply-chain and reproducibility risk.

NPX is a NPM tool that lets devs run Node packages without global installs. It’s handy for executing binaries from Node modules and running packages that leave no trace after execution.

NVM, on the other hand, is a version manager that lets you install multiple Node.js versions and switch between them effortlessly. It’s crucial for testing apps across Node versions or maintaining projects tied to specific Node versions.

Real-Life Scenario: Streamlined Project Setup

Imagine a backend dev juggling legacy Node.js versions and modern standards for a new microservice. Here’s how NPX and NVM can help:

Setting Up the Development Environment:
- The developer can use nvm to switch between Node versions as needed. For instance, starting with Node 12 for compatibility testing:
  1 2
  
  nvm install 12 nvm use 12
- They then use npx to run a scaffolding tool like express-generator without installing it globally:
  1
  
  npx express-generator my-new-service
Development and Testing:
- As development progresses, testing on newer Node versions is necessary. Here, nvm allows easy switching:
  1
  
  nvm use 14
- Using npx, the developer can run local tests with tools like mocha without permanent installations:
  1
  
  npx mocha
CI/CD Integration:
- In a continuous integration setup, ensuring that the microservice builds and runs tests across all supported Node versions can be scripted using both nvm and npx:
  1 2
  
  nvm exec 12 npx npm test nvm exec 14 npx npm test

This isolates microservices from version conflicts and global deps, ensuring each is tested and deployed with the right Node env.

Using the tools together

The combination of NPX and NVM can significantly reduce setup times, avoid conflicts between differing Node module versions, and facilitate a cleaner development environment. Backend developers benefit from:

Flexibility in managing multiple Node.js environments.
Convenience of running any Node.js package executably without prior installation.
Efficiency in testing across different environments with minimal configuration changes.

Debug Flow-Invoked Queueable Apex with Correlated Logs

Yoonsoo Park — Sun, 28 Apr 2024 00:00:00 +0000

This guide was verified against Salesforce documentation on 2026-08-01.

Why the old debugging flow changed

The archived article started with a Flow invoking an @future method. Salesforce now recommends Queueable Apex for production asynchronous work: it returns a job ID, accepts structured state, supports chaining, and is easier to monitor. A more important debugging detail was also missing. The Flow transaction and Queueable transaction are separate executions. Their logs can have different traced entities, timestamps, and governor-limit contexts.

A useful trace must connect those transactions without logging an access token, Named Credential secret, customer payload, or full HTTP response.

Current mental model

Treat the path as three observable boundaries:

Flow interview validates inputs and invokes a bulk-safe Apex action.
Invocable Apex creates a correlation ID, enqueues one or more jobs within limits, and returns or persists the job ID.
Queueable Apex runs later, under its own transaction and limits, and can be found through AsyncApexJob.

The Flow debugger proves the synchronous path. Apex debug logs and AsyncApexJob prove the asynchronous path. Neither alone proves the complete business outcome.

A correlation-friendly implementation

Keep the invocable method bulk-safe. Don’t enqueue one job per record without considering the per-transaction queueable limit. The example groups the inputs into one job and generates a nonsecret correlation value.

public with sharing class SyncAccountsAction {
public class Request {
@InvocableVariable(required=true)
public Id accountId;
}
@InvocableMethod(label='Queue Account Sync')
public static void enqueue(List<Request> requests) {
Set<Id> accountIds = new Set<Id>();
for (Request request : requests) {
if (request != null && request.accountId != null) {
accountIds.add(request.accountId);
}
}
if (accountIds.isEmpty()) return;
String correlationId = Crypto.getRandomUUID();
Id jobId = System.enqueueJob(
new SyncAccountsJob(new List<Id>(accountIds), correlationId)
);
System.debug(LoggingLevel.INFO,
'account-sync queued correlation=' + correlationId + ' job=' + jobId);
}
}

public with sharing class SyncAccountsJob
implements Queueable, Database.AllowsCallouts {
private final List<Id> accountIds;
private final String correlationId;
public SyncAccountsJob(List<Id> accountIds, String correlationId) {
this.accountIds = accountIds;
this.correlationId = correlationId;
}
public void execute(QueueableContext context) {
System.debug(LoggingLevel.INFO,
'account-sync started correlation=' + correlationId
+ ' job=' + context.getJobId() + ' count=' + accountIds.size());
// Query only required fields. Use a Named Credential for callouts.
// Log status, duration, and a provider request ID—not secrets or bodies.
}
}

If the correlation must survive log expiration, store a minimal status record containing the correlation ID, Queueable job ID, state, timestamps, and a sanitized error code. Apply retention and sharing rules; an observability object must not become a second store for customer payloads.

Set the right trace flags

Reproduce in a sandbox or scratch org with the smallest useful log window.

Trace the user who launches the Flow for the synchronous interview and invocable call.
When automation runs as Automated Process, add a trace flag for Automated Process as well.
Keep Apex Code at a useful level such as FINE or FINEST only during the short diagnostic period. Raising every category to the maximum creates truncation and hides the useful sequence.
If a scheduled or platform-event path starts the work, identify its actual execution user instead of assuming it matches the browser user.

Trigger one known record and note the start time and correlation ID. Then query the job:

1
2
3
4
5
6


sf data query --target-org sandbox --use-tooling-api --query \
 "SELECT Id, Status, JobType, ApexClass.Name, CreatedDate, CompletedDate,
 NumberOfErrors, ExtendedStatus
 FROM AsyncApexJob
 WHERE ApexClass.Name = 'SyncAccountsJob'
 ORDER BY CreatedDate DESC LIMIT 10"

Use the returned job ID and timestamps to locate the Queueable log. A Completed job means the Queueable transaction completed; it does not necessarily mean the remote system accepted or applied the business operation. Verify the external outcome through a safe provider request ID or a business-state query.

Secret-safe logging

Log identifiers that help correlation: job ID, correlation ID, record count, sanitized error category, HTTP status, duration, and an upstream request ID. Do not log:

access or refresh tokens;
Named Credential material or authorization headers;
full request or response bodies;
customer fields not required for diagnosis;
stack traces in user-visible Flow errors.

Catch expected integration failures, persist a sanitized operational status, and let unexpected exceptions fail the Queueable so AsyncApexJob records the failure. Avoid swallowing an exception after printing it.

Limits and tradeoffs

Queueable Apex is the default choice for single-shot asynchronous production work, but it still shares daily asynchronous capacity and has enqueue limits. Batch Apex is more appropriate for very large query-driven datasets. Platform Events can decouple producers and consumers, at the cost of event delivery and monitoring complexity. A synchronous invocable action is simplest when the work is quick and does not require a callout after DML.

Chaining can express ordered stages, but every link needs an idempotency and stop strategy. Don’t build an unbounded retry loop. Use a bounded retry count, backoff appropriate to the external service, and a terminal failure state that an operator can inspect.

Migration checklist

Inventory each Flow that calls @future and document its inputs and side effects.
Create a bulk-safe invocable boundary and a Queueable class with focused tests.
Add a correlation ID and retain the System.enqueueJob job ID.
Replace raw endpoints and secrets with a Named Credential.
Define sanitized success, retryable failure, and terminal failure states.
Test one record, a Flow-sized batch, callout failure, permission failure, and limit behavior.
Deploy to a sandbox, add short-lived trace flags for the real execution identities, and compare business outcomes.
Activate the revised Flow through a controlled release and remove obsolete trace flags.

Verification

A complete verification connects the Flow interview to the invocable log, the Queueable job ID, its asynchronous log, and the final business result. Tests should assert that inputs are bulked, the Queueable is enqueued, callouts are mocked, errors are classified without secrets, and retries terminate.

Official sources

How to Fork a Repository, Make Changes, and Update a Submodule in Your Main Project

Yoonsoo Park — Sat, 20 Apr 2024 00:00:00 +0000

How to Fork a Repository, Make Changes, and Update a Submodule in Your Main Project

Forking a repository on GitHub allows you to freely experiment with changes without affecting the original project. This is particularly useful in software development where you might want to customize a library, theme, or any other shared project to suit your own needs. In this blog, we will walk through the process of forking a repository, making updates, and then using those changes in a main project by updating a submodule.

Step 1: Forking a Repository

Forking creates a copy of someone else’s repository under your GitHub account, allowing you to make changes without impacting the original repo. Here’s how to fork a repository:

Navigate to the Repository: Go to the GitHub page of the repository you want to fork.
Fork the Repository: Click the “Fork” button usually located at the top right of the page. This action will create a copy of the repository in your GitHub account.

Step 2: Cloning Your Fork

Once you have forked the repository, you will need to clone it to your local machine to make changes:

Copy the Repository URL: On your fork’s GitHub page, click the “Code” button and copy the URL provided.
Clone the Repository: Open a terminal and run git clone [URL], replacing [URL] with the repository URL you copied. This downloads the repository to your local machine.

Step 3: Making Changes in Your Fork

With the repository cloned, you can now navigate into the directory and start making changes:

Navigate to the Repository Directory: cd repository-name
Create a New Branch (optional but recommended): git checkout -b your-new-branch-name
Make Your Changes: Use your favorite code editor to make the changes you desire.
Commit the Changes: Use git add . to stage changes, and git commit -m "your commit message" to save them.

Step 4: Pushing Changes and Updating Your Fork

After committing your changes locally, you need to push them back to your GitHub fork:

Push the Changes: git push origin your-new-branch-name
Create a Pull Request (if you want to contribute back to the original repository): Go to your fork on GitHub, switch to your branch, and click “Pull request”.

Step 5: Updating a Submodule in Your Main Project

If your fork is used as a submodule in another project, update your main project to use the latest changes:

Navigate to the Submodule Directory: cd path-to-main-project/submodule-directory
Pull the Latest Changes: git checkout main (or whichever branch you want), then git pull origin main
Commit the Submodule Changes in the Main Project: Navigate back to the root of your main project, then run git add submodule-directory and git commit -m "Update submodule to latest commit"
Push the Updates: git push origin main

Retargeting a submodule to a fork

Removing .git/modules is unnecessary when only the remote URL changes. Use the supported URL workflow first:

1
2
3
4
5


git submodule set-url themes/hugo-tania https://github.com/yourusername/hugo-tania.git
git submodule sync --recursive
git submodule update --init --recursive
git add .gitmodules themes/hugo-tania
git commit -m "Point theme submodule to maintained fork"

The superproject records a specific submodule commit, not a floating branch. Review and commit that pointer deliberately.

Full removal as a fallback

Sometimes you might find it necessary to replace a submodule in your project with a fork that you have customized. This section will guide you through removing the existing submodule and adding your fork as the new submodule. In this example, we will assume that you have forked the hugo-tania theme and want to use it in your project. (the blog you are reading is using this theme).

Step 1: Navigate to Your Main Project

Ensure you are in the root directory of your main project where the submodule is integrated:

1

cd path/to/your/main/project

Step 2: Remove the Existing Submodule Reference

To change the submodule reference, first, remove the existing submodule. This includes deleting the submodule’s entries from .gitmodules, .git/config, and the actual submodule directory:

1
2
3


git submodule deinit -f themes/hugo-tania
rm -rf .git/modules/themes/hugo-tania
git rm -f themes/hugo-tania

Step 3: Commit the Removal of the Submodule

Commit these changes to ensure your repository correctly reflects the removal of the submodule:

1

git commit -m "Remove old submodule reference"

Step 4: Add Your Fork as the New Submodule

Now, add your fork as the new submodule. This step points the submodule reference to your forked repository:

1

git submodule add https://github.com/yourusername/hugo-tania.git themes/hugo-tania

Step 5: Initialize and Update the Submodule

After adding the new submodule, initialize and update it to make sure it’s correctly set up:

1

git submodule update --init --recursive

Step 6: Commit the New Submodule Reference

Once the submodule is added and updated, you need to commit these changes to your project’s repository:

1
2


git add .gitmodules themes/hugo-tania
git commit -m "Update submodule to point to my fork"

Step 7: Push Your Changes

Finally, push the changes to your remote repository to ensure that everything is up-to-date:

1

git push origin main

This procedure ensures that your main project now uses the updated fork as a submodule, allowing you to benefit from your custom changes or enhancements. This approach is ideal for developers who need to modify dependencies while keeping track of their changes separately from the original submodule source.

Understanding the Git Remote Named 'origin'

Yoonsoo Park — Fri, 05 Apr 2024 00:00:00 +0000

In the realm of Git and GitHub, grasping the concept of origin is crucial for developers to effectively manage and collaborate on code. The term origin might sound abstract, but it plays a critical role in your interactions with Git repositories. This article demystifies origin, breaking down its importance and functionality in the context of GitHub.

Remote Repository Alias

origin is a conventional Git remote name created by git clone, not a GitHub feature and not a guarantee. Inspect it with git remote -v; repositories can rename it or have several remotes.

When you clone a repository from GitHub, Git doesn’t leave you juggling with the full URL of your remote repository every time you need to interact with it. Instead, it kindly sets up a shorthand alias named origin. This alias points directly to the URL of the cloned repository, simplifying your command-line operations.

For instance, pushing changes to the origin means you are updating the remote repository you originally cloned from:

1

git push origin branch-name

This command efficiently communicates your local changes back to the remote repository, tagged under the branch you specify. push your local branch-name to origin(remote repo where you cloned your code from)

Default Remote

The term origin is not a whimsical choice but a standard convention in Git to refer to your primary remote repository. However, this doesn’t mean you are stuck with it. Git is flexible, allowing you to rename origin to something more meaningful to you or even work with multiple remotes by giving each one a unique name.

Independence from the Default Branch

While origin is a constant presence in your Git commands, it’s important to note that it does not tie specifically to any branch, such as the default main or master branch. Instead, origin is your gateway to the entire remote repository, providing access to all its branches. For example, if you need to fetch updates from a develop branch on the remote, you’d use:

1

git fetch origin develop

This command doesn’t care which branch is default; it fetches updates from develop, demonstrating origin’s versatility.

Wrapping it up

The concept of origin in GitHub is a cornerstone for efficient repository management and collaboration. It is essentially a nickname or alias for the remote repository from which you cloned your code!

Setting Up a Shortcut for GitHub Copilot in VS Code

Yoonsoo Park — Mon, 25 Mar 2024 00:00:00 +0000

GitHub Copilot has become an indispensable tool for many developers, offering AI-powered code suggestions that streamline the coding process. However, constantly navigating through menus to access Copilot can disrupt your workflow. This tutorial will guide you through setting up a keyboard shortcut in Visual Studio Code (VS Code) to quickly open the GitHub Copilot chat panel.

Step-by-Step Guide to Setting Up Your Shortcut

Command IDs and default bindings can change with VS Code and the Copilot extension. Open Keyboard Shortcuts, search for the current Copilot Chat command by name, assign a non-conflicting key, and use the conflict view to verify context.

Open the Command Palette in VS Code Start by opening the Command Palette, which is the hub for accessing various commands in VS Code. You can open it by pressing Cmd + Shift + P on your keyboard.
Access Keyboard Shortcuts File In the Command Palette, type keyboard shortcuts json. This will bring up a list of options related to keyboard shortcuts. Select Preference: Open Keyboard Shortcuts (JSON) from the list. This action opens the keybindings.json file where you can define custom keyboard shortcuts.

Edit the JSON File In the keybindings.json file, you will define the shortcut for the GitHub Copilot chat panel. Insert the following code snippet:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


{
 "key": "ctrl+alt+cmd+c",
 "command": "workbench.panel.chat.view.copilot.focus",
 "when": "editorFocus"
},
{
 // Move focus back to the Editor
 "key": "ctrl+alt+cmd+c",
 "command": "workbench.action.focusActiveEditorGroup",
 "when": "!editorFocus"
}

This configuration sets up Ctrl + Alt + Command + C as the shortcut to toggle the GitHub Copilot chat panel. The first part focuses on the Copilot chat panel when the editor is focused, and the second part returns focus to the editor if the Copilot panel is focused.

Save and Test Your Shortcut After adding the code, save your keybindings.json file. Test the new shortcut by pressing Ctrl + Alt + Command + C in the editor. If everything is set up correctly, you should be able to toggle the GitHub Copilot chat panel with this shortcut.

Wrapping it up

After saving the binding, invoke it in the intended editor context and confirm that it opens the current Copilot Chat command without shadowing another shortcut.

Node.js Guide to package.json and package-lock.json

Yoonsoo Park — Wed, 20 Mar 2024 00:00:00 +0000

In the realm of Node.js development, understanding the nuances of package.json and package-lock.json is crucial for building and maintaining robust applications. These files are not just placeholders in your project; they are pivotal in defining, managing, and ensuring the consistency of your application’s dependencies across different environments. This article delves deep into the anatomy of package.json and package-lock.json, underscores their critical roles, and provides a real-life scenario that showcases their utility.

Understanding `package.json`

The package.json file acts as the backbone of any Node.js project, offering a snapshot of your project’s metadata and dependencies. Here’s a detailed exploration:

Basic Purpose of `package.json`

Project Metadata: It encapsulates essential details like your project’s name, version, and description, which are vital for both documentation and identification purposes.
Dependency Management: This is where package.json truly shines, listing all necessary dependencies and devDependencies, thus allowing Node.js to fetch and install them appropriately.
Scripts: It enables you to define script commands for various tasks such as starting your app or running tests, streamlining your development workflows.
License Information: Indicates the legal licensing under which the project is released.

Advanced Usage of `package.json`

Versioning and npm Workflows: Embracing semantic versioning and utilizing npm’s capabilities for version management can significantly enhance your project’s reliability.
Custom Scripts: Beyond standard scripts, you can introduce custom automation scripts for tasks like linting, building, or deployment.
Package Configuration: Certain npm packages offer the option to be configured directly within package.json, fostering a centralized configuration approach.
Peer Dependencies: Essential for library authors, this section ensures consumers have the compatible dependency versions installed.
Engines: Specify which Node.js engine versions your project is compatible with, ensuring consistency across development and deployment environments.
Private Packages: Mark your package as private to prevent unintentional publishing to npm.

How Node.js Installs Dependencies

When dependencies are declared in package.json, Node.js uses npm to install them as follows:

Parsing package.json: npm examines package.json to identify the required dependencies and their specified versions.
Resolving Dependencies: npm determines the exact versions to install, adhering to the version ranges specified. It ensures that the installed versions meet the version constraints while considering the latest versions available.
Downloading and Installing: npm fetches and installs the dependencies from the npm registry. The dependencies are installed for production, and devDependencies are additionally installed in development environments.
Storing Dependencies: Installed packages are placed in the node_modules directory within your project, allowing Node.js to access and load them as needed.
Version Locking: npm generates a package-lock.json to lock down the exact versions installed, ensuring consistent installs across environments.

Real-Life Example

Imagine a web application project that uses several dependencies, such as Express for the backend and React for the frontend. package.json lists these dependencies with specified version ranges. When setting up the project on a new machine or deployment environment, npm consults package.json to install the exact versions of these libraries, as recorded in package-lock.json, ensuring that the application behaves consistently across different setups and avoiding the “works on my machine” problem.

package-lock.json: Ensuring Consistency

Commit the root package-lock.json for an npm-managed project and use npm ci in CI when an exact clean install is required. Review engines, packageManager, workspaces, and overrides as explicit project policy; the lockfile is generated output and should not be hand-edited.

While package.json provides a broad overview and intent of your project’s dependencies, package-lock.json nails down the exact versions of each installed package, ensuring that your project remains consistent and predictable across all installations. It records the specific version of each package that is installed and guarantees that the same version is used every time you (or anyone else) runs npm install.

Best Practices for Maintaining `package-lock.json`

Version Control: Always check in package-lock.json into your version control system. This inclusion ensures that every collaborator or deployment environment uses precisely the same set of dependencies.
Regular Updates: Dependencies should be updated methodically to incorporate critical security patches, bug fixes, or new features. npm update can

be your ally here, modifying package-lock.json to reflect updated versions.

Conflict Resolution: In case of merge conflicts in package-lock.json, it’s generally safe to regenerate it by deleting the existing file and running npm install, ensuring alignment with package.json.
Using npm ci: In continuous integration environments, prefer npm ci over npm install to adhere strictly to the versions defined in package-lock.json, enhancing the reliability of your builds.
Avoid Manual Edits: You should not manually edit package-lock.json as it can lead to inconsistencies. If there’s a need to change a version of a package, do it through package.json and let npm update the lock file accordingly.
Review Changes: When package-lock.json is updated (for instance, when adding a new package), review the changes to ensure that the versions are correct and there are no unexpected modifications.

Conclusion

Grasping the intricacies of package.json and package-lock.json is fundamental for any Node.js developer aiming to build reliable, maintainable, and consistent applications. Do not be a developer, just execute npm run all without knowing what it is about. Fundamental matters in every part of life so is this.

Testing Dependencies in Node.js Projects - A Focus on Package.json

Yoonsoo Park — Tue, 19 Mar 2024 00:00:00 +0000

Dependency management is a critical factor in the development of Node.js projects, significantly influencing the reliability and maintainability of applications. For teams that maintain their own libraries in conjunction with main projects, the task of debugging and testing these dependencies can pose unique challenges. This article explores a situation where a Node.js library, referred to as @yopa/the-library, requires comprehensive testing within a primary project to validate its functionality.

The Challenge: Debugging Internal Libraries

Imagine you’re working on a Node.js project, and your application relies on an internal library you’ve developed and maintained. This library, referred to as @yopa/the-library, is crucial for your application’s functionality. However, when issues arise in your main project, it’s essential to pinpoint whether the problem lies within the project itself or is due to the integrated library.

Traditionally, this library is managed as a npm package and versioned something like @yopa/the-library: ^1.12.10, which introduces complexity when attempting to debug interactions between the library and the main project. This becomes even more challenging when you need to modify the library code and test these changes directly within the main project.

A Strategic Approach to Dependency Testing

Prefer a workspace, a file: dependency, or npm pack to test the exact library artifact. npm link is useful for live iteration but can change module resolution and produce duplicate singleton dependencies. Do not delete lockfiles or rewrite package.json without preserving and reviewing the diff.

To efficiently tackle this challenge, the following steps provide a systematic method for testing and debugging the library within the context of the main project:

Local Packaging of the Library: Begin by making the necessary modifications to your library code. Once the changes are ready for testing, execute npm pack in the library’s root directory. This command generates a .tgz file, essentially a zipped version of your library, which you can then integrate directly into your main project.
Modifying package.json Dependencies: Navigate to the package.json file in your main project. Update the dependency entry for the-library to point to the absolute path of the .tgz file you generated, rather than specifying a version number. This change directs npm to use the local version of the library for installation.
Installation and Deployment: With the dependency path updated, run npm install to integrate the local version of your library into the main project.
Iterative Testing and Debugging: As you continue to refine and test your library, you’ll need to update the .tgz file regularly. This involves running npm run build (assuming your library requires a build step) and npm pack again to create a new package reflecting your latest changes. After updating the package, use npm i ./path/to/tgzfile.tgz in your main project to test the updated library.

By adopting this workflow, you can directly test how changes in your library affect the main project, enabling rapid iteration and more effective debugging.

A Note of Gratitude

In the realm of software development, collaboration and mutual learning are key to overcoming challenges and achieving success. I’d like to extend my sincere gratitude to my team members, Steven and Ryan, for their insights, support, and the collaborative spirit they bring to our projects. Working alongside such dedicated individuals is not only inspiring but also immensely educational.

Wrapping it up

By utilizing local packaging and strategic modifications in package.json, developers can achieve a more integrated and responsive debugging environment.

Understanding Metadata API vs Tooling API in Salesforce Development

Yoonsoo Park — Mon, 18 Mar 2024 00:00:00 +0000

When developing in Salesforce, understanding the nuanced differences between Metadata API and Tooling API can significantly streamline your workflow. Both are powerful interfaces for interacting with your org’s metadata, but they serve distinct purposes and are suited to different kinds of tasks. Let’s delve into the specifics of each API and explore real-life examples to guide you on when to use one over the other.

Metadata API: Configuration Lifecycle

Metadata API retrieves, deploys, creates, updates, or deletes supported customization metadata. Its defining concern is configuration lifecycle, not merely operation size.

Real-Life Example: Full-Scale Deployment

Imagine you’re working on a major update for your Salesforce org, which includes new custom objects, updated page layouts, several new fields, and modified permissions. Here, the Metadata API shines by helping you to package all these changes and deploy them from your sandbox environment to production efficiently. It’s akin to moving an entire library of books from one room to another, ensuring nothing is left behind.

Tooling API: Developer Tooling Objects

Tooling API exposes objects used by developer tools, including Apex execution, tests, coverage, traces, and selected development artifacts. It isn’t a universal fine-grained replacement for Metadata API.

Real-Life Example: Iterative Development

Consider a scenario where you’re developing a new custom application within Salesforce and need to frequently create, test, and modify individual Apex classes and Visualforce pages. The Tooling API is your best friend here, enabling quick iterations and immediate feedback on your changes. It’s like fine-tuning a single book’s layout and content, ensuring every page is perfect before the final print.

Choosing the Right API for Your Task

Choose by resource and lifecycle rather than size alone:

Use Metadata API when:
- You’re deploying or retrieving supported configuration metadata.
- Your work involves complex metadata types and dependencies.
- You’re migrating changes across environments (e.g., sandbox to production).
Use Tooling API when:
- You’re building developer tooling around Apex, tests, traces, and coverage.
- You need Tooling API objects documented for the operation.

For business records or application UI, evaluate REST, Composite, GraphQL, or UI API instead. Pin an API version, grant least privilege, handle limits, and test in a nonproduction org. Reviewed against Salesforce’s official API documentation on 2026-08-01.

Mastering SF CLI - In-Depth Guide to sf project convert source and mdapi Commands

Yoonsoo Park — Sun, 17 Mar 2024 00:00:00 +0000

Salesforce CLI (Command Line Interface) continues to evolve, introducing sophisticated tools to enhance the efficiency and structure of Salesforce project management. Among the noteworthy updates are the sf project convert source and sf project convert mdapi commands, crucial for transitioning project formats and aiding developers in their deployment and development workflows. This article explores these commands in depth, examining their features, differences, and strategic importance in the Salesforce development landscape.

Exploring `sf project convert source`

sf project convert source transforms source-formatted files into Metadata API format for consumers that explicitly require that representation. Ordinary Salesforce CLI deployments can deploy source format directly, so conversion is not a default deployment step.

Features and Advantages:

Preparation for Deployment: It readies source-formatted files for deployment, ensuring they are compatible with Metadata API–dependent Salesforce environments.
Efficient Workflow Management: By allowing developers to work in the Source format and convert files as needed, it supports a seamless transition from development to deployment.

Practical Examples:

This command allows for flexible directory and package specification, illustrated by these examples:

Converting a source directory to the metadata format: $ sf project convert source --root-dir path/to/source
Defining an output directory and package name: $ sf project convert source --root-dir path/to/source --output-dir path/to/output --package-name 'My Package'

Reevaluating `sf project convert mdapi`

The sf project convert mdapi command complements sf project convert source by converting Metadata API format files back to the Source format, supporting a reverse workflow.

Features and Advantages:

Transition to Source Format: It simplifies the move to Source format, beneficial for version control, collaboration, and CI/CD integration.
Legacy Integration: It’s crucial for developers migrating from Metadata API–based projects to the modular Source format.

Treat converted output as an ephemeral interoperability artifact. Keep one source of truth in Git and avoid editing both representations.

Comparing Metadata API and Source Format Structures

Understanding the structural differences between Metadata API and Source formats is essential for leveraging the full potential of the conversion commands.

Metadata API Format Illustration:

The Metadata API format groups similar types of metadata, potentially complicating detailed version control. An example structure is as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


unpackaged/
├── classes
│ ├── MyApexClass.cls
│ └── MyApexClass.cls-meta.xml
├── objects
│ ├── MyCustomObject__c.object
│ └── AnotherObject__c.object
├── pages
│ └── MyVisualforcePage.page
└── package.xml

Source Format Illustration:

The Source format, on the other hand, offers a granular component breakdown, aiding in precise change management and conflict resolution:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


force-app/
├── main/
│ └── default/
│ ├── classes/
│ │ ├── MyApexClass.cls
│ │ └── MyApexClass.cls-meta.xml
│ ├── objects/
│ │ ├── MyCustomObject__c/
│ │ │ ├── fields/
│ │ │ │ └── MyField__c.field-meta.xml
│ │ │ └── MyCustomObject__c.object-meta.xml
│ │ └── AnotherObject__c/
│ │ └── AnotherObject__c.object-meta.xml
│ └── pages/
│ └── MyVisualforcePage.page-meta.xml
└── sfdx-project.json

These distinctions highlight the strategic considerations in choosing the appropriate command based on the project’s phase and requirements.

Wrapping it up 👏

Use sf project deploy preview and sf project deploy start --dry-run before direct deployment. Convert only at a legacy-tool or package boundary, write to a clean build directory, and verify the resulting package.xml. Reviewed against the Salesforce CLI reference on 2026-08-01.

How to Fix Divergent Branch Problems in Git - A Step-by-Step Guide.

Yoonsoo Park — Tue, 12 Mar 2024 00:00:00 +0000

When working with Git, you might encounter a situation where your branches have diverged, leading to confusion and potential merge conflicts. This blog post will delve into what causes divergent branches in Git and how to reconcile them effectively.

Understanding Divergent Branches in Git

Divergent branches occur when your local branch and the corresponding remote branch have different commits. This situation typically arises when multiple people are working on the same branch or when changes are made to the remote branch after you’ve cloned or fetched it but before you try to push your local changes.

When you attempt to git pull, Git may show a message indicating that you have divergent branches and need to specify how to reconcile them. This is because Git wants to prevent unintentional loss of work and ensure that you are making a conscious decision about how to integrate the changes.

Strategies to Reconcile Divergent Branches

There are three main strategies to reconcile divergent branches in Git:

1. Merge

Merging is the most straightforward approach. It combines the histories of the two branches, creating a new merge commit. This approach maintains the full history of both branches but can lead to a more complex commit history.

1
2


git config pull.rebase false
git pull origin <branch-name>

2. Rebase

Rebasing rewrites the commit history by applying your local changes on top of the remote branch’s latest commit. It results in a cleaner, linear history but should be used with caution as it changes commit hashes.

1
2


git config pull.rebase true
git pull origin <branch-name>

The Significance of the Rebase Warning

The warning “but should be used with caution as it changes commit hashes” during a rebase is crucial to understand. When you rebase a branch, Git essentially creates new commits for each commit in your branch since it diverged from the base branch. This process changes the commit hashes, which are the unique identifiers for each commit.

Why is this Important?

Collaboration Impact: If you’ve already pushed your branch and then rebase it, the rebased branch will not align with the remote branch since the commit hashes have changed. If someone else is working on the same branch, they will encounter conflicts when they try to pull your changes.
Data Integrity: Changing commit hashes can also impact any references to those commits, such as in submodules, or when using commit hashes in documentation or issue tracking.
Force Pushing: After a rebase, you’ll need to force push (git push --force) to update the remote branch with the rewritten history. Force pushing can be risky as it can overwrite changes on the remote branch, so it should be done with caution and clear communication among team members.

3. Fast-forward only

The fast-forward only approach refuses to merge if the local branch has diverged from the remote branch, ensuring that your history only ever moves forward linearly from the base.

1
2


git config pull.ff only
git pull origin <branch-name>

Setting a Default Reconciliation Strategy

You can set your preferred strategy globally or per repository, providing flexibility and control over your project’s version control strategy.

1
2
3
4
5


# Set globally
git config --global pull.rebase false

# Set for a specific repository
git config pull.rebase false

You can set this setting globally by adding --global to the git config command, but it’s generally safer to set them per-repository (which I prefer) unless you are certain about this.

Conclusion

Understanding how to manage divergent branches in Git is critical for maintaining a clean workflow in your development. By choosing the appropriate strategy to reconcile branches, you can ensure that your project’s history is manageable, reducing potential integration headaches down the line. (ultimate goal!)

Conclusion

Whether you prefer merging, rebasing, or fast-forwarding, Git provides the ways you need to maintain a consistent history in your version control.

Choosing a Python Project and Dependency Workflow

Yoonsoo Park — Mon, 11 Mar 2024 00:00:00 +0000

Python’s environment and packaging ecosystem offers several valid workflows. Moving from venv to Pipenv is not automatically an upgrade: venv creates an isolated environment, while workflow tools may additionally resolve dependencies, create locks, build packages, publish artifacts, or run tasks. Start with the capabilities a repository needs.

This guide was verified on 2026-08-01 against the Python Packaging User Guide tool recommendations, the venv documentation, and the reproducible-environments specifications.

Current mental model

Separate four concerns:

An interpreter manager, such as pyenv, selects a Python release.
An environment manager isolates installed packages. Standard venv is the minimal baseline.
A resolver selects compatible dependency versions.
A build backend creates a wheel or source distribution when the project is packaged.

A single tool may cover several concerns, but the project should still document which files are authoritative and which outputs are regenerated.

A safe minimal baseline

1
2
3
4
5
6


python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m pip check
python -m pytest

Use python -m pip to make the target interpreter explicit. Keep .venv/ out of Git. For an application that requires fully repeatable deployments, add the repository’s chosen lock or compiled-constraints workflow rather than relying on an old environment’s pip freeze output.

Choosing among tools

venv plus pip is broadly available and easy to debug, but does not prescribe one lock workflow.
pip-tools compiles reviewed requirement inputs into pinned outputs and fits many existing pip deployments.
Pipenv manages a virtual environment and Pipfile.lock; keep it when the team and automation already depend on that contract.
Poetry and PDM provide project metadata, resolution, locking, and packaging workflows with different conventions.
Hatch focuses on project environments, builds, publishing, and task-like scripts.
uv provides fast environment and dependency workflows and supports several modern Python packaging standards.

Tool popularity is not a migration requirement. Evaluate supported Python versions, platform behavior, private index authentication, lock portability, CI installation, editor support, and maintainer continuity.

Migration without deleting evidence

Record the current interpreter, direct dependency declarations, lock or constraints files, and successful test commands.
Create a new branch and a separate clean environment. Do not delete the working environment yet.
Configure the candidate tool from direct project intent, not by declaring every transitive package as direct.
Resolve and inspect changes in versions, hashes, indexes, and platform markers.
Run unit, integration, build, and smoke tests on every supported platform.
Update CI and onboarding documentation in the same change.
Prove a clean clone can reproduce the workflow before removing the old files.

Never make rm -rf venv the first migration step. An environment is disposable only after its requirements and working verification commands are preserved.

Application versus library tradeoffs

Applications often lock the complete deployable environment. Libraries generally declare compatible dependency ranges so downstream applications can resolve them. Test a library against its supported range rather than publishing an application-style lock as a consumer requirement.

For standalone Python commands, use pipx to isolate the installed application. For CI publishing to PyPI, prefer trusted publishing where supported rather than a long-lived upload token.

Verification gate

1
2
3
4


python -c 'import sys; print(sys.executable, sys.version)'
python -m pip check
python -m build
python -m pytest

Use only commands relevant to the repository, but require a clean-clone installation and the same production entry point used before migration. Keep the old workflow available until the new path passes those gates and the rollback is understood.

Operational checks after migration

A resolver change can affect installation time, cache behavior, artifact size, private-index requests, and failure messages in CI. Confirm that dependency automation can still update the authoritative declaration and that developers do not need personal credentials in committed configuration. Test an unavailable index so bootstrap fails clearly instead of using an unexplained global package.

Document how to add, remove, and update a direct dependency; how to regenerate resolved output; and which files reviewers inspect. Include the supported Python matrix and the command that proves the active interpreter. A future teammate should reproduce the environment from a clean checkout without knowing which tool was popular when the repository was created.

Update Notifications in Node.js with TypeScript

Yoonsoo Park — Mon, 26 Feb 2024 00:00:00 +0000

Keeping your Node.js application up-to-date is crucial for security, performance, and feature enhancements. The update-notifier npm package, when used with TypeScript, provides a powerful yet straightforward way to notify users of your application about new updates. This blog delves into the integration of update-notifier within a TypeScript environment, covering both basic and advanced usages with detailed code examples.

Introduction to Update-Notifier with TypeScript

update-notifier is a handy tool for Node.js applications to check for available updates and notify users, ensuring they are always using the latest version. Integrating it with TypeScript adds type safety and enhances code readability and maintainability.

Setting Up Your TypeScript Project

Before diving into update-notifier, ensure your TypeScript environment is set up. You’ll need a tsconfig.json file configured for your project. Here’s a basic setup:

1
2
3
4
5
6
7
8
9


{
 "compilerOptions": {
 "target": "es5",
 "module": "commonjs",
 "strict": true,
 "esModuleInterop": true,
 "resolveJsonModule": true
 }
}

The resolveJsonModule option in compilerOptions allows TypeScript to natively import JSON modules, such as your package.json file. This is crucial for update-notifier to access the current version and package name.

Installing Update-Notifier

Current update-notifier releases include TypeScript declarations and are ESM. Confirm the package version and Node module mode before using the examples. Notifications should be disabled in CI and non-interactive output, and should never block the command.

To add update-notifier to your project, run:

1

npm install update-notifier

The second command installs the TypeScript type definitions for update-notifier, allowing for type checking and IntelliSense in your IDE.

Basic Usage in TypeScript

After ensuring your tsconfig.json is properly configured to import JSON modules, you can now easily import your package.json:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


import updateNotifier from "update-notifier";
import pkg from "./package.json";

const notifier = updateNotifier({
 pkg,
 updateCheckInterval: 1000 * 60 * 60 * 24,
});

if (notifier.update) {
 notifier.notify();
}

This script will check for updates once a day and notify the user when there’s a new version available.

Advanced Usage Examples

Prompting Users to Update

You can prompt users interactively to update their application using inquirer alongside update-notifier. Here’s a TypeScript example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


import updateNotifier from "update-notifier";
import inquirer from "inquirer";
import pkg from "./package.json";
import { execSync } from "child_process";

const notifier = updateNotifier({ pkg });

if (notifier.update) {
 inquirer
 .prompt([
 {
 type: "confirm",
 name: "update",
 message: `Update available: ${notifier.update.latest}. Do you want to update now?`,
 default: false,
 },
 ])
 .then((answers: any) => {
 if (answers.update) {
 execSync(`npm install -g ${pkg.name}`, { stdio: "inherit" });
 }
 });
}

Custom Notifications Based on Update Type

You can customize the notification message based on the update type (major, minor, patch) using TypeScript’s enum and type checking features:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26


import updateNotifier, { UpdateInfo } from "update-notifier";
import pkg from "./package.json";

const notifier = updateNotifier({ pkg });

if (notifier.update) {
 let message: string = "";
 const update: UpdateInfo = notifier.update;

 switch (update.type) {
 case "major":
 message =
 "A new major version is available. Updating is highly recommended!";
 break;
 case "minor":
 message =
 "A new minor version is available. Update to access new features.";
 break;
 case "patch":
 message =
 "A new patch version is available. Update to improve stability.";
 break;
 }

 notifier.notify({ message });
}

Logging Update Details

For more detailed logging, especially useful in debugging or maintaining logs, you can utilize TypeScript to ensure structured and type-safe logging:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


import updateNotifier from "update-notifier";
import pkg from "./package.json";

const notifier = updateNotifier({ pkg });

if (notifier.update) {
 console.log(`Update available: ${notifier.update.latest}`);
 console.log(`Current version: ${pkg.version}`);
 console.log(`Update type: ${notifier.update.type}`);
}

Conclusion

Update notifications should be a non-blocking convenience. Respect CI and non-interactive environments, provide an opt-out where appropriate, and do not make network availability a requirement for the command to succeed.

Structured CLI Tasks with Listr2

Yoonsoo Park — Mon, 19 Feb 2024 00:00:00 +0000

Introduction

Listr2 presents structured progress for multi-step CLI operations. Use it when task hierarchy helps users understand progress, while retaining plain and complete output for CI and logs.

Why Listr?

Elegant Task Displays: Unlike traditional CLI outputs, Listr introduces clean layouts, spinners, and status symbols that significantly enhance visual appeal and user comprehension.
Organized Workflows: Listr allows for the breaking down of complex tasks into manageable subtasks, reflecting the logical structure of operations and facilitating easier troubleshooting.
Progress Tracking: Real-time updates provided by Listr foster trust and a sense of responsiveness, keeping users informed about the script’s execution status.

Getting Started (with TypeScript)

Before diving into Listr, ensure you have a compatible Node.js environment. Listr’s TypeScript support offers strong typing benefits, making your task management scripts more maintainable and error-resistant.

The original listr package is superseded by listr2, which includes its own TypeScript types. Pin a compatible release and configure a non-interactive renderer for CI, logs, and redirected output. Progress UI must not hide command failures.

Install Listr and types:
1

npm install listr @types/listr

A simple TypeScript example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25


import { Listr } from "listr2";
import type { ListrTask } from "listr2";

// Define a context for your tasks to use
interface MyContext {
 downloadPath: string;
}

const tasks = new Listr<MyContext>([
 {
 title: "Download project assets",
 task: (ctx) => downloadAssets(ctx.downloadPath),
 // Here, downloadAssets is a function you define to download project assets
 },
 {
 title: "Process data",
 task: () => processData(),
 // processData is another function for handling your data
 },
]);

// Run the tasks with a specified context
tasks.run({ downloadPath: "/tmp" }).catch((err) => {
 console.error(err);
});

Listr’s Flexibility in Action

Error Handling: Efficient error management is crucial for resilient script execution. Listr enables specific error handling routines and rollback mechanisms to maintain stability.

1
2
3
4
5
6
7
8


const tasks = new Listr<MyContext>([
 {
 title: "Fetch sensitive data",
 task: () => fetchData(), // fetchData should safely handle sensitive information
 onRollback: (task, ctx) => cleanUpSensitiveFiles(ctx.tempFiles),
 // cleanUpSensitiveFiles is a custom cleanup function
 },
]);

Observability: Tracking task progress is simplified with Listr’s event hooks, offering insights into each step’s execution.

1
2
3
4
5


const tasks = new Listr([...], { rendererOptions: { showSubtasks: false } });

tasks.on('task:start', (task) => {
 console.log(`Starting task: ${task.title}`);
});

Customization: Tailor Listr’s output to meet your needs, whether for a concise summary or detailed logs.
1

const tasks = new Listr([...], { renderer: 'verbose' });

Real-World Use Cases

Deploying Listr in practical scenarios demonstrates its versatility and impact:

Build Script Example: Simplify your build process with structured tasks, making each step transparent and manageable.

1
2
3
4
5


tasks.add([
 { title: "Clean", task: () => runCleanCommand() },
 { title: "Transpile Code (TypeScript)", task: () => transpileCode() },
 { title: "Bundle Assets", task: () => bundleAssets() },
]);

Deployment Workflow Example: Streamline deployments by organizing tasks sequentially, ensuring each step is completed before proceeding.

1
2
3
4
5
6
7
8
9


tasks.add([
 { title: "Test Suite", task: () => runTestSuite() },
 { title: "Push to Staging", task: () => deployToStaging() },
 {
 title: "Monitor",
 task: () => monitorLogs(),
 enabled: (ctx) => ctx.deploySuccess,
 },
]);

**Wrapping it up **

Listr2 is useful when interactive progress materially improves a multi-step command. Review its current official documentation, and keep the underlying task functions independent from the renderer.

Mastering Salesforce CLI with Grep - A Guide to Finding Commands Efficiently

Yoonsoo Park — Sun, 11 Feb 2024 00:00:00 +0000

Salesforce CLI now has built-in discovery commands. Start with sf search, sf commands, command help, shell completion, and sf which; use grep only as a fallback for narrowing text output.

1. Finding Basic Commands

Starting with the basics, let’s say you need to find commands related to organizations (orgs). The Salesforce CLI has various org-related commands, but to find them quickly:

1

sf org --help | grep "org"

This command filters the extensive help information of sf org to lines containing “org”, giving you a quick overview of available org commands.

2. Locating Commands for Data Manipulation

Often, you’ll need to manipulate data, like querying or exporting data. For instance, to find commands related to querying data:

1

sf data --help | grep "query"

This reveals options and subcommands under sf data that are related to querying, making it easier to find the exact syntax or command you need.

3. Searching for Deployment Commands

Deployment is a critical task, and you need to get the commands right. If you’re looking for commands related to deploying metadata:

1

sf project deploy start --help | grep -i "test\|target"

This filters out the specific options and subcommands for metadata deployment, simplifying the task of finding the right command for your deployment needs.

4. User Management Commands

Managing users is a common task. To find commands related to user creation or management:

1

sf user --help | grep "create"

This command is particularly useful when you’re looking to create new users and need to know the specific command and its options.

5. Environment and Instance Management

For managing your environments or instances, you might need specific commands. To find those:

1

sf env --help | grep "list"

This is helpful to list all environments or instances, providing you with the exact command to use.

Advanced Tips

Case-Insensitive Search: Use grep -i for a case-insensitive search, which is particularly useful if you’re unsure about the casing.
Extended Patterns: Use egrep or grep -E for more complex pattern searches.
Contextual Search: If you need more context around your search, use grep with -B, -A, or -C to display lines before, after, or around the matching line.

A better discovery sequence

Run sf search, inspect sf <topic> --help, then open the exact command’s help. Use sf which <command> to identify its plugin and sf commands for an inventory. grep is Unix-specific and can hide surrounding context, so documentation and built-in help remain the source of truth. Verified against the Salesforce CLI discovery guide on 2026-08-01.

Testing TypeScript with Jest

Yoonsoo Park — Sat, 10 Feb 2024 00:00:00 +0000

In the realm of JavaScript and TypeScript development, testing your code is just as important as writing it. Jest, a delightful JavaScript Testing Framework, has gained immense popularity for its simplicity and feature-rich environment. When combined with TypeScript, it brings strong typing and helps catch errors early, leading to more reliable and maintainable code. In this article, we dive deep into how to use Jest with TypeScript, exploring its powerful features through practical examples.

Setting up Jest with TypeScript

This setup uses ts-jest and Jest transforms. Native ESM projects require different configuration and mocking rules; follow the current Jest ESM guide instead of copying CommonJS assumptions.

Before harnessing the power of Jest in a TypeScript environment, you need to set up your project correctly. Start by installing TypeScript, Jest, and the necessary dependencies:

1

npm install --save-dev typescript jest @types/jest ts-jest

Then, initialize TypeScript in your project:

1

npx tsc --init

Configure Jest to work with TypeScript by editing your Jest configuration file (jest.config.js):

1
2
3
4


module.exports = {
 preset: "ts-jest",
 testEnvironment: "node",
};

Writing Your First Jest Test in TypeScript

With the setup ready, let’s dive into writing a basic test. Consider a simple function in sum.ts:

1
2
3
4


// sum.ts
export function sum(a: number, b: number): number {
 return a + b;
}

You can write a test for this function in sum.test.ts:

1
2
3
4
5
6


// sum.test.ts
import { sum } from "./sum";

test("adds 1 + 2 to equal 3", () => {
 expect(sum(1, 2)).toBe(3);
});

Run your tests using:

1

npx jest

Exploring Matchers in Jest

Matchers are the heart of Jest’s testing power, allowing you to write various assertions.

Common Matchers

Matchers in Jest are methods that let you test values in different ways. These methods are used with the expect function to assert whether a particular value meets certain conditions. Jest offers a wide range of matchers, allowing you to handle various scenarios in your tests, from simple equality checks to more complex checks like testing for exceptions or checking array contents.

toBe and toEqual:

toBe uses Object.is to test exact equality. It’s great for primitive types.
toEqual recursively checks every field of an object or array.

1
2
3
4
5
6
7
8
9


test("two plus two is four", () => {
 expect(2 + 2).toBe(4);
});

test("object assignment", () => {
 const data: { [key: string]: number } = { one: 1 };
 data["two"] = 2;
 expect(data).toEqual({ one: 1, two: 2 });
});

Truthiness:

toBeNull matches only null.
toBeUndefined matches only undefined.
toBeDefined is the opposite of toBeUndefined.
toBeTruthy matches anything that an if statement treats as true.
toBeFalsy matches anything that an if statement treats as false.

1
2
3
4
5
6
7
8


test("null", () => {
 const n: null = null;
 expect(n).toBeNull();
 expect(n).toBeDefined();
 expect(n).not.toBeUndefined();
 expect(n).not.toBeTruthy();
 expect(n).toBeFalsy();
});

Numbers:

Matchers like toBeGreaterThan, toBeLessThan, etc., are used for comparing numbers.

1
2
3
4
5


test("two plus two", () => {
 const value: number = 2 + 2;
 expect(value).toBeGreaterThan(3);
 expect(value).toBeLessThan(5);
});

Strings:

toMatch is used to check strings against regular expressions.

1
2
3


test("there is no I in team", () => {
 expect("team").not.toMatch(/I/);
});

Arrays and Iterables:

toContain checks if an array or iterable contains a particular item.

1
2
3
4
5
6
7
8
9


test("the shopping list has beer on it", () => {
 const shoppingList: string[] = [
 "diapers",
 "kleenex",
 "trash bags",
 "beer",
 ];
 expect(shoppingList).toContain("beer");
});

Exceptions:

toThrow checks if a function throws an error when it’s called.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


function compileAndroidCode(): void {
 throw new Error("you are using the wrong JDK");
}

test("compiling android goes as expected", () => {
 expect(compileAndroidCode).toThrow();
 expect(compileAndroidCode).toThrow(Error);
 expect(compileAndroidCode).toThrow("you are using the wrong JDK");
 expect(compileAndroidCode).toThrow(/JDK/);
});

Custom Matchers

Jest allows you to extend its matchers by using expect.extend to add your custom matchers. This is useful when you want to add reusable test logic, or if you’re testing something specific to your application.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31


// Extend the expect type with a custom matcher
declare global {
 namespace jest {
 interface Matchers<R> {
 toBeDivisibleBy(argument: number): R;
 }
 }
}

expect.extend({
 toBeDivisibleBy(received: number, argument: number) {
 const pass = received % argument === 0;
 if (pass) {
 return {
 message: () =>
 `expected ${received} not to be divisible by ${argument}`,
 pass: true,
 };
 } else {
 return {
 message: () => `expected ${received} to be divisible by ${argument}`,
 pass: false,
 };
 }
 },
});

test("even and odd numbers", () => {
 expect(100).toBeDivisibleBy(2);
 expect(101).not.toBeDivisibleBy(2);
});

Matchers are a powerful part of Jest, providing a rich vocabulary for writing tests. They help make your tests expressive and ensure that your code behaves as expected. The variety and extensibility of Jest matchers make them suitable for a wide range of testing scenarios.

Setup and Teardown

Jest offers several functions that allow you to perform setup and teardown tasks in your tests. These functions are beforeAll, beforeEach, afterAll, and afterEach. They are particularly useful for preparing the environment for tests and cleaning up afterward. Here’s a detailed look at each of these functions:

1. `beforeAll`

This function runs once before all the tests in a describe block. It’s useful for setting up something that is needed by all the tests and is expensive to set up, like a database connection or a large dataset.

1
2
3


beforeAll(() => {
 // Setup code that runs once before all tests
});

2. `beforeEach`

beforeEach runs before each test in a describe block. This is useful for resetting conditions to a known state before every test, such as resetting database records or clearing mocks.

1
2
3


beforeEach(() => {
 // Setup code that runs before each test
});

3. `afterAll`

This function is called once after all the tests in a describe block have completed. It is used for cleanup activities that need to happen after all tests have run, like closing database connections or freeing up resources that were used during the tests.

1
2
3


afterAll(() => {
 // Cleanup code that runs once after all tests
});

4. `afterEach`

afterEach is executed after each test in a describe block. It’s often used for cleanup that should be performed after each test, like resetting mock functions or clearing changes made during the individual test.

1
2
3


afterEach(() => {
 // Cleanup code that runs after each test
});

Example Usage

Here’s an example that demonstrates how these functions might be used in a test suite:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35


describe("Test Suite", () => {
 beforeAll(() => {
 // This will run once before all the tests in this suite
 // Assuming initializeDatabase is a function you've defined
 initializeDatabase();
 });

 beforeEach(() => {
 // This will run before every test
 // Assuming resetTestData is a function you've defined
 resetTestData();
 });

 test("Test 1", () => {
 // Test code here
 // Example: expect(someFunction()).toBe(someValue);
 });

 test("Test 2", () => {
 // Test code here
 // Example: expect(someOtherFunction()).toEqual(someOtherValue);
 });

 afterEach(() => {
 // This will run after each test
 // Assuming clearMocks is a function you've defined
 clearMocks();
 });

 afterAll(() => {
 // This will run once after all the tests in this suite
 // Assuming closeDatabaseConnection is a function you've defined
 closeDatabaseConnection();
 });
});

In this example, initializeDatabase and closeDatabaseConnection are used for setting up and tearing down the database, which is a relatively heavy operation, so it’s done once. resetTestData and clearMocks are lighter operations needed to ensure each test runs in a clean state, so they are done before and after each test.

These functions help in organizing the test code and managing resources efficiently, making the tests more reliable and maintainable.

Conclusion

Jest, when used with TypeScript, provides a robust framework for writing and managing your tests. Its rich set of matchers, combined with TypeScript’s strong typing, ensures that your tests are both powerful and maintainable.

Choose a Salesforce Package Model: 1GP, Managed 2GP, or Unlocked

Yoonsoo Park — Mon, 05 Feb 2024 00:00:00 +0000

Verified against Salesforce documentation on 2026-08-01.

Why the old comparison was archived

Packaging isn’t a linear upgrade from 1GP to 2GP. The earlier article incorrectly suggested that a namespace-free package could later be promoted into a managed package and described dependencies as flexible version ranges. Package type, namespace, ancestry, and version dependencies are lifecycle decisions with constraints.

Decision model

Maintain an existing managed 1GP product when migration cost and compatibility outweigh 2GP benefits.
Choose managed 2GP for a new commercial or partner-distributed application that needs namespacing, upgrade lineage, and AppExchange lifecycle.
Choose unlocked packages for internal modular delivery where source control is authoritative and subscribers control installation.
Use unmanaged packages only for templates or one-time sharing, not an upgradeable product.

Managed packages require deliberate namespace and Dev Hub planning. An unlocked package without a namespace does not become a managed package by promotion. Dependencies identify package versions; validate the exact dependency graph instead of assuming arbitrary semantic ranges.

Safe workflow

1
2
3
4
5
6


sf package create --name BillingCore --package-type Unlocked \
 --path force-app --target-dev-hub dev-hub
sf package version create --package BillingCore \
 --installation-key-bypass --wait 20 --target-dev-hub dev-hub
sf package version promote --package 04t... --target-dev-hub dev-hub
sf package install --package 04t... --target-org test --wait 20

Never promote before installing the version in a clean org and running Apex, permission, upgrade, and dependency tests. Protect installation keys and do not print auth URLs in CI.

Tradeoffs

Unlocked packages favor internal autonomy but don’t provide the same intellectual-property and subscriber controls as managed packages. Managed 2GP improves source-driven releases but makes namespace, ancestry, and version choices durable. 1GP remains valid for established products, although new development loses many 2GP workflow benefits. Direct metadata deployment is simpler for a small org but provides no package installation boundary.

Migration checklist

Inventory subscribers, namespace, package IDs, dependencies, and upgrade promises.
Decide internal versus external distribution and ownership of upgrades.
Prototype the chosen model in a separate Dev Hub and disposable org.
Define package directories and dependency versions in sfdx-project.json.
Test fresh install, upgrade, uninstall behavior, permissions, and data migration.
Promote only an immutable version that passed the release gate.
Document rollback; package promotion itself isn’t a rollback mechanism.

Verification and sources

Confirm the package/version IDs in the Dev Hub, install into an empty org, upgrade from the oldest supported version, and run the complete test suite.

Git Diff for Working Trees, Commits, and Branches

Yoonsoo Park — Sat, 27 Jan 2024 00:00:00 +0000

In the realm of version control with Git, understanding the git diff command is crucial for developers. This post not only explores the basics but also dives into advanced uses of git diff, complete with detailed examples and code blocks for a comprehensive understanding.

Basic Usage of Git Diff

1. Viewing Uncommitted Changes

git diff

This command shows the differences between your working directory and the index (staging area). It’s helpful to review changes before staging them.

Example:

Suppose file.txt originally contains “Hello, World!” and you add “New line” to it. Running git diff will show:

1
2
3
4
5
6
7


diff --git a/file.txt b/file.txt
index ce01362..b6fc4c8 100644
--- a/file.txt
+++ b/file.txt
@@ -1 +1,2 @@
 Hello, World!
+New line

2. Viewing Changes That Are Staged for Commit

git diff --staged

This compares your staged changes with the last commit, useful for a final review before committing.

3. Comparing Two Files Within the Working Directory

git diff -- file1.txt file2.txt

This compares two local files, showing differences even if they aren’t tracked by Git.

Advanced Usage of Git Diff

1. Difference Between Two Branches

Use base...topic to inspect changes introduced since the merge base, as a pull request usually does. Use base..topic only when an endpoint tree comparison is intended.

git diff main..feature-branch

This shows the changes between the main branch and feature-branch, useful for reviewing changes before merging branches.

Example:

Suppose in your main branch, you have a file hello.txt with “Hello, World!”, and in your feature-branch, it’s changed to “Hello, Git World!”. The command git diff main..feature-branch will show the differences.

2. Difference Between Two Commits

git diff <HASH-OLDER-COMMIT>..<HASH-NEWER-COMMIT>

This is for comparing specific commits, perhaps to understand the changes introduced in a feature branch.

3. Diff a File Across Branches or Commits

git diff main feature-branch file.txt

This focuses on how a single file (file.txt) differs between the main branch and feature-branch.

4. Diff a File Over Time in the Same Branch

First step: git log --before="2023-01-01" --after="2022-01-01" --follow -- file.txt

Then: git diff <old-commit-hash>..<new-commit-hash>

This combination is great for tracking a file’s evolution over a specified period.

5. Diff a File That Has Been Renamed

git diff <old-commit-hash>..<new-commit-hash>

Git automatically tracks renamed files post Git 2.9, making it easier to see changes to files even after renaming.

Advanced Features

Combining Diffs

git diff <commit1>..<commit2>..<commit3>

This aggregates changes from multiple commits into one view, simplifying code review or audits.

Diff with Context

git diff --unified=5 <commit1>..<commit2>

This shows more surrounding lines (context) around changes for better understanding.

Word Diff

git diff --word-diff <commit1>..<commit2>

It breaks down the differences to the word level, offering a more granular view.

Ignoring Space Changes

git diff -w <commit1>..<commit2>

This ignores white space changes, focusing only on actual content changes.

Conclusion

Use git diff by first choosing the two states you intend to compare: working tree, index, commit endpoints, or a merge base. Review path exclusions carefully so important generated or policy files remain visible.

How to Check if Google Analytics is Working

Yoonsoo Park — Thu, 25 Jan 2024 00:00:00 +0000

Ensuring that your Google Analytics is set up correctly is crucial for accurately tracking your website’s traffic. While the Realtime report in Google Analytics provides immediate data about active users on your site, it doesn’t guarantee the absence of issues like duplicate tracking codes, which can distort your data significantly.

To accurately check your website for such discrepancies, Google offers a powerful tool: the Google Tag Assistant. This tool is not just a basic checker; it’s an essential instrument for anyone serious about accurate data analytics.

How to Use Google Tag Assistant Tool

Google Tag Assistant allows you to identify and fix issues such as duplicate tracking codes, ensuring that your data reflects actual user behavior. Here’s how you can use this tool to verify your Google Analytics setup:

Access Tag Assistant: Start by visiting tagassistant.google.com.
Choose Your Assessment Method: You have two options: assess a domain directly on the site or use the Tag Assistant Companion browser extension in Chrome for a more integrated experience.

3. Add Your Domain: Click the ‘Add domain’ button to start the assessment process for your specific domain.

4. Connect Your Domain: After clicking ‘Connect’, your website will open in a new window. Don’t close this window; it’s crucial for the assessment process.

5. Review Installed Tags: Return to the Tag Assistant tab to review the tags installed on your site. This is where you can see if you have any duplicate or incorrect implementations. In our example, we noticed a UA container and a Google Analytics 4 container.

By following these steps, you’re not just checking if Google Analytics is working; you’re ensuring that it’s working correctly. The Tag Assistant tool is a definitive way to verify your setup, giving you confidence in the data you’re using to make important business decisions.

Wrapping it up 👏

Accurate data is the cornerstone of effective web analytics. By utilizing the Google Tag Assistant, you’re taking a crucial step towards ensuring the integrity of your data. Remember, in the world of analytics, precision matters. Don’t just track; track correctly. Cheers to data-driven success!

Cheers! 🍺

Understanding Git Revert vs. Manual Reversion - Best Practices for Code Rollbacks

Yoonsoo Park — Wed, 24 Jan 2024 00:00:00 +0000

When it comes to undoing changes in your codebase, Git offers powerful tools that help maintain stability and traceability in your projects. Two common methods for reverting changes are using the git revert command and manually reverting through a series of commands including git checkout. Both methods have their uses, but understanding their nuances is key to choosing the right approach for your situation. In this article, we will explore each method, complete with examples, to help you make informed decisions when you need to roll back changes. Let’s go.

Method 1: Using Git Revert

The git revert command is the standard way to undo changes in Git. It creates a new commit that reverses the changes made by a previous commit. This method doesn’t alter the project’s history, making it safe and transparent, especially in collaborative environments.

Example of Git Revert

Imagine you’ve made a commit that unexpectedly breaks your application. The commit ID is abc1234. To revert this commit, you would use the following commands:

1
2


git revert abc1234
git push

This sequence of commands creates a new commit that undoes the changes made in commit abc1234, then pushes this new commit to your remote repository.

Benefits of Git Revert

Preserves History: Keeps the original commit in the history, alongside the revert commit, maintaining a complete and traceable record.
Collaboration Friendly: Clearly communicates the reversion to team members, maintaining clarity in shared repositories.

Method 2: Restore selected paths and commit the correction

The manual reversion method involves checking out the state of a specific commit, manually resetting your files to that state, and then creating a new commit with those changes. This method gives you more control but requires careful handling to ensure clarity and traceability.

Example of Manual Reversion

Suppose you want to revert to the state of your project at commit def5678. You would use the following sequence of commands:

1
2
3
4


git restore --source=def5678 --staged --worktree -- path/to/file
git add path/to/file
git commit -m "Manually reverting to the state of commit def5678"
git push

This sequence manually reverts your project to the state of commit def5678 and then pushes this new state to your remote repository.

Benefits of Manual Reversion

More Control: Allows you to manually adjust the state of your files, offering flexibility in complex scenarios where an automatic revert might not suffice.
Hands-On Approach: Useful for quick rollbacks locally or when you want to carefully craft the state of your project.

Choosing the Right Method

While both methods can revert changes, choosing the right one depends on your specific needs:

Use git revert when:
- You’re working in a collaborative environment.
- You need to maintain a clear and traceable history.
- The changes you’re reverting are straightforward and don’t require manual intervention.
Consider manual reversion when:
- The changes you need to revert are complex or require manual intervention.
- You’re working locally and need a quick rollback, and you’re confident about managing your project’s history.

Conclusion

Whether you choose the automated git revert or the manual checkout and commit approach, understanding the implications of each method on your project’s history and collaboration dynamics is key. Use git revert for its clarity and traceability, especially in collaborative settings. Opt for manual reversion when you need more control over the process. Remember, the goal is not just to undo changes, but to do so in a way that maintains the integrity and understandability of your project history.

Resolve CloudFront CNAMEAlreadyExists Without an Avoidable Outage

Yoonsoo Park — Tue, 23 Jan 2024 00:00:00 +0000

CloudFront returns CNAMEAlreadyExists when the alternate domain name you want is already associated with another CloudFront distribution or distribution tenant. DNS may still point at the old resource, but deleting the DNS record alone does not necessarily remove the CloudFront association and can create an avoidable outage.

Prepare the target first

The target distribution must be deployed and include a valid TLS certificate from ACM in us-east-1. The certificate’s subject alternative names must cover the domain you are moving. Configure origins, cache behavior, security policy, logging, and error responses before changing production traffic.

Confirm the AWS account and distribution IDs:

1
2


aws sts get-caller-identity --profile production
aws cloudfront get-distribution --id TARGET_ID --profile production

Do not copy a domain between accounts based on a partial distribution ID from an error message.

Find the conflict

AWS recommends the newer ListDomainConflicts operation because it supports both standard distributions and distribution tenants. ListConflictingAliases supports standard distributions and remains relevant for older workflows. The caller needs permission for the operation and access to the target resource used in the ownership check.

Use the current console, SDK, or AWS CLI command available in your installed CLI version. Inspect exact and wildcard conflicts: *.example.com can overlap www.example.com even when the literal alias is not obvious.

If you own both resources and they are in the same account, update the source and target through the documented move procedure. Depending on resource type and account boundary, AWS supports AssociateAlias or UpdateDomainAssociation. Cross-account movement requires domain ownership proof, commonly through the documented DNS TXT record, and appropriate permissions on both sides.

Avoid DNS-first troubleshooting

Lower DNS TTL ahead of a planned move when appropriate, but do not remove a working record simply to clear the API error. CloudFront’s alias association and public DNS are separate state. Prepare and validate the target, move the association with the supported operation, update DNS if the target hostname changes, and keep the source available through propagation and cache windows.

Test the target before the public cutover where possible:

1
2


curl --resolve www.example.com:443:TARGET_EDGE_IP \
 https://www.example.com/health

Because CloudFront edge IPs change and direct testing has caveats, follow the documented target-validation method for the migration type. Verify certificate hostname, response headers, origin routing, redirects, cache keys, cookies, and authenticated paths—not only the home page.

Failure and rollback

If AWS says the source is in another account you do not control, do not attempt to seize it. Verify DNS ownership and open an AWS Support case using the official process. Never publish account IDs, distribution details, or certificate validation records in a public ticket.

Keep the source configuration and DNS values recorded. A rollback may require moving the alias back; DNS reversal alone is insufficient if CloudFront now associates the alias with the target. Monitor CloudFront 4xx/5xx, origin errors, TLS failures, cache hit behavior, and application checks during the change window.

Checklist

Confirm account, source, target, exact alias, and wildcard overlap.
Deploy target behavior and an us-east-1 certificate covering the alias.
Use the supported conflict-list and association/move operation.
Prove ownership for cross-account movement.
Coordinate alias and DNS changes; do not delete DNS as a first fix.
Validate critical paths and monitoring before and after cutover.
Preserve a tested reverse-move rollback plan.

Official documentation reviewed on 2026-08-01:

Safe Container Updates on a Personal Docker Host

Yoonsoo Park — Mon, 22 Jan 2024 00:00:00 +0000

Automatic container replacement looks like maintenance, but it is also an unattended production deployment. Pulling a mutable latest tag and restarting several stateful services can introduce a breaking application or database migration with no reviewed change, tested backup, or rollback artifact.

For a personal Docker or Synology host, the practical goal is not “never automate.” It is to separate discovery from deployment and make each update observable and recoverable.

The current mental model

Use automation to detect new images and notify you. Promote a specific version or digest during a maintenance window after reviewing release notes. Back up persistent data, update one dependency group at a time, verify health and user workflows, then retain the previous image until the rollback window closes.

Watchtower can still be useful, especially in monitor-only mode. Mounting /var/run/docker.sock gives a container powerful control over the Docker daemon, effectively a host-level trust boundary. Run only a pinned, trusted Watchtower image; limit the containers it observes with labels or an explicit list; and do not expose its API publicly.

Pin the deployment

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23


services:
 app:
 image: ghcr.io/example/app:2.4.1
 restart: unless-stopped
 healthcheck:
 test: ["CMD", "wget", "-q", "--spider", "http://localhost:8080/health"]
 interval: 30s
 timeout: 5s
 retries: 5
 volumes:
 - app-data:/var/lib/app

 watchtower:
 image: containrrr/watchtower:1.7.1
 command: --monitor-only --label-enable --notifications-level info
 environment:
 WATCHTOWER_SCHEDULE: "0 30 8 * * 1"
 volumes:
 - /var/run/docker.sock:/var/run/docker.sock
 restart: unless-stopped

volumes:
 app-data:

Watchtower uses a six-field cron expression that includes seconds. 0 30 8 * * 1 means Monday at 08:30. A traditional five-field expression can be rejected or mean something other than intended. Confirm the schedule in the version you actually deploy.

The example enables monitoring only for containers labeled com.centurylinklabs.watchtower.enable=true. Notification configuration depends on the chosen provider; test it before relying on it.

Maintenance-window procedure

Read application and image release notes, including required intermediate upgrades and schema changes.
Record the current image reference and Compose configuration.
Stop application writes if the product requires a consistent backup.
Back up volumes and external databases, then perform a restore test periodically. A successful archive command is not proof of recoverability.
Change the image to a specific version or immutable digest and pull it.
Recreate the affected service without deleting dependencies or volumes.
Wait for the health check, then test login, reads, writes, scheduled jobs, and dependent services.
Watch logs and resource use through the rollback window.

If the new version fails before a one-way data migration, restore the previous image reference. If it migrated data incompatibly, follow the application’s documented downgrade path or restore the pre-update backup. Simply starting the old image against a newer schema can make damage worse.

Tradeoffs

Full automatic updates reduce patch delay but accept unreviewed breaking changes. Monitor-only automation needs human time but preserves a decision gate. A registry digest is immutable and ideal for reproducibility, while a version tag is more readable but depends on publisher tag discipline. Renovate or Dependabot can propose Compose changes in Git and provide a review trail; that is valuable when the host configuration is managed as code.

For disposable stateless services, auto-update plus strong health and rollback automation may be reasonable. For databases, media indexes, identity services, or anything with irreplaceable state, require a maintenance gate.

Do not confuse a container’s healthy status with application acceptance. A health endpoint can succeed while authentication, background jobs, storage permissions, or integrations are broken. Keep a short smoke-test list for the services you actually use. On Synology, also verify Container Manager still points to the intended project, volume paths retain their permissions, and reverse-proxy routes reach the recreated container.

Migration checklist

Replace latest with a version or digest.
Move Watchtower to monitor-only before changing deployment policy.
Correct schedules to six-field syntax and verify timezone.
Add real health checks and notifications.
Inventory volumes, databases, configuration, and secrets; document backup and restore.
Test one service group, dependency ordering, and rollback.
Remove unused images only after the rollback period.
Review Docker socket access and keep the management UI private.

Verified on 2026-08-01.

Primary sources

Understanding and Managing Narcissistic Behaviors in Everyday Life

Yoonsoo Park — Sun, 21 Jan 2024 00:00:00 +0000

In our daily interactions, whether in personal relationships or professional settings, understanding the complexities of human behavior can be crucial. One particularly challenging personality type is the narcissist. Rooted in Wendy T. Behary’s insightful book, “Disarming the Narcissist: Surviving and Thriving with the Self-Absorbed”, this blog post aims to elucidate the characteristics of narcissistic behaviors and offer pragmatic approaches for dealing with individuals who exhibit these traits.

Recognizing Narcissistic Behaviors

Narcissistic individuals often display a pattern of traits and behaviors that can be disruptive and challenging to those around them. Key characteristics include:

Grandiosity: A pervasive sense of superiority, often accompanied by an exaggeration of talents and achievements.
Example: Imagine a colleague, John, who frequently boasts about his business acumen and success. He often exaggerates his role in successful projects and claims his strategies are superior to anyone else’s in the industry. Despite evidence to the contrary, he maintains an inflated perception of his importance and capabilities.
Need for Admiration: A continuous quest for excessive attention and admiration.
Example: Sarah, a team leader, constantly seeks validation and praise from her peers and subordinates. She requires her team to commend her for every decision she makes, regardless of its impact, and becomes noticeably upset or agitated when her work isn’t acknowledged or praised excessively.
Sense of Entitlement: Unreasonable expectations of especially favorable treatment and automatic compliance with their expectations.
Example: Mark expects special treatment at work. He believes he should be exempt from regular duties such as submitting reports on time or attending mandatory meetings. When asked to comply, he reacts indignantly, questioning why he, given his perceived status, should follow the same rules as everyone else.
Exploitative Relationships: Taking advantage of others to achieve personal ends without empathy or consideration.
Example: Lisa often manipulates her colleagues to do her work under the guise of needing help due to her “overwhelming” workload. She rarely reciprocates or acknowledges their assistance and is quick to take full credit for the collective efforts and successes.
Lack of Empathy: An inability or unwillingness to recognize and honor the feelings and needs of others.
Example: During a team crisis where everyone is under stress, Alex remains indifferent to his colleagues’ struggles. He dismisses their concerns and emotions, focusing solely on how the situation benefits or harms his personal agenda, showing little to no regard for the collective morale or well-being.
Envy: Feelings of resentment towards others’ achievements or a belief that others are envious of them.
Example: Whenever a co-worker receives a compliment or a promotion, Emily reacts with subtle derogatory remarks or attempts to undermine their achievements. She feels resentful when others succeed or are recognized, perceiving it as a direct threat to her status.
Arrogance: Displaying snobbish, disdainful, or patronizing attitudes.
Example: In meetings, Tom often talks down to his peers, dismissing their ideas and input as inferior or irrelevant. He displays a patronizing attitude, believing his insights are the only ones of value and expecting others to conform to his viewpoint without question.

It’s worth noting that these traits can be present in anyone and may not necessarily indicate a personality disorder. However, when these behaviors are pervasive, persistent, and negatively impact one’s life and relationships, they can be indicative of Narcissistic Personality Disorder (NPD).

Strategies for Dealing with Narcissists

In “Disarming the Narcissist,” Behary not only paints a detailed picture of the narcissistic personality but also offers valuable strategies for interacting with individuals exhibiting these traits. Some of these strategies include:

Setting Clear Boundaries: Communicate your limits assertively and consistently to prevent boundary overstepping.
Avoiding Power Struggles: Engage selectively in conflicts. Focus on maintaining personal peace and professional integrity instead of winning every battle.
Using ‘We’ Language: Frame discussions in an inclusive manner to avoid triggering defensiveness and encourage cooperation.
Acknowledging Their Strengths: Recognize and appreciate the narcissist’s abilities and achievements to make them more receptive to communication.
Keeping Emotions in Check: Stay calm and composed, especially when the narcissist tries to provoke emotional reactions.
Seeking Support: Build a support network for guidance and validation when dealing with challenging dynamics.
Documenting Interactions: Keep records of interactions, especially in professional settings, to maintain an objective account of events.
Focusing on Solutions: Steer conversations towards constructive outcomes rather than dwelling on problems.

Wrapping it up 👏

Navigating relationships with narcissistic individuals can be challenging, but with understanding and the right strategies, it’s possible to maintain a sense of balance and peace. The book, “Disarming the Narcissist: Surviving and Thriving with the Self-Absorbed”, provides not just a lens to understand narcissism but also practical tools to manage and thrive in the presence of narcissistic behaviors. Whether in personal relationships or professional arenas, these insights are invaluable for fostering healthier and more constructive interactions.

Instead of falling into the role of a victim, arm yourself with these strategies and tame them.

Here’s to all who bravely navigate these turbulent waters! Godspeed. Cheers. 🍺

Environment Variables in Shell Scripts with set -a

Yoonsoo Park — Sat, 20 Jan 2024 00:00:00 +0000

Managing environment variables effectively is crucial in the realm of shell scripting, especially when dealing with complex projects that rely on external configurations. Traditionally, the source command is used to import variables from .env files. However, this article takes you a step further, illustrating the meticulous art of combining .env files with the set -a and set +a shell commands for a more robust and secure approach to environment variable management.

Understanding the Basics

Before diving deep, it’s important to grasp the basics. An environment variable is a dynamic-named value that can affect the way running processes will behave on a computer. For instance, they can store information about the default text editor or browser, the path to executable files, or the system locale and language.

.env files are a simple and popular method to configure environment variables. They are plain text files containing key-value pairs, making them easy to create and manage. However, variables defined in .env files aren’t automatically available in the shell script. They need to be explicitly imported.

The Role of `source .env`

Sourcing a file executes it as shell code; .env is not a universal data format. Only source a file you control, quote its path, restrict its permissions, and keep secrets in the deployment platform secret store.

The source command, used as source .env, executes the file passed as an argument, in the current shell. It reads and imports environment variables from .env into the shell session, but it doesn’t export them to child processes by default.

Elevating with `set -a` and `set +a`

This is where set -a and set +a come into play. These commands elevate the way environment variables are handled in shell scripts.

set -a (Automatic Export): When you run set -a before sourcing your .env file, it automatically exports the variables defined after it. This means the variables are not just available to the script but also to any subprocesses or commands that the script executes. It ensures that the environment is consistent and predictable, not just in your script but in other tools or scripts that your script might call.
set +a (Revert Automatic Export): After importing your variables, set +a is used to revert the shell back to its default behavior. It’s a good practice, preventing any further variables from being automatically exported. This limits the scope of set -a to only the variables you intend to export, minimizing side effects and enhancing security.

Why Use `set -a` and `set +a`?

Using these commands provides several benefits:

Explicitness & Clarity: Clearly shows the intent to export the variables, making scripts more readable and maintainable.
Security: By isolating the export behavior to a specific block of code, you reduce the risk of unintentionally exposing variables.
Consistency & Compatibility: Ensures consistent behavior in variable exportation across different environments and shell versions.

Practical Example: Deploying a Web Application

Imagine you're tasked with deploying a web application. This application requires several environment variables to run, such as database connection strings, API keys, and configuration flags. These variables differ between development, staging, and production environments.

Steps in the Deployment Script

Your deployment script might include steps like:

Setting Up the Environment: Load environment variables from a .env file corresponding to the target environment (development, staging, or production).
Running Database Migrations: Execute scripts to set up or update the database schema.
Starting Services: Start the application backend, frontend, and any auxiliary services, each of which requires access to the environment variables.

Why `set -a` and `set +a` are Useful Here

Isolation of Environment Variables: You have a .env file for each environment (.env.development, .env.staging, .env.production). Using set -a and set +a ensures that only the variables from the specific .env file are exported, preventing any accidental overlap or leakage between environments.
Ensuring Subprocess Compatibility: The database migration scripts, backend, frontend, and auxiliary services are likely separate processes or even separate scripts that are called from your main deployment script. By using set -a, you ensure that these subprocesses inherit the necessary environment variables, ensuring a smooth and predictable deployment process.
Security and Cleanliness: After loading and exporting the necessary variables, set +a is used to prevent any future variables defined in your script from being automatically exported. This is particularly important for maintaining the security and cleanliness of your environment, as only the necessary variables are exposed to subprocesses.

Script Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


#!/bin/sh

# Choose the right .env file based on the target environment
ENV_FILE=".env.production"

# Automatically export variables
set -a
. ""
set +a

# Run database migrations
./run_database_migrations.sh

# Start services
./start_backend.sh
./start_frontend.sh
./start_aux_services.sh

# ... rest of your deployment script

In this script:

set -a ensures all variables from .env.production are exported and available to the run_database_migrations.sh, start_backend.sh, start_frontend.sh, and start_aux_services.sh scripts.
set +a ensures that any variables defined or modified after this point in the script are not automatically exported, maintaining a clean and secure environment.

Conclusion

While source .env works fine for simple cases, the combination of set -a and set +a offers a controlled, secure, and clear approach to managing environment variables in shell scripts. It’s a testament to the thoughtfulness that goes into professional script writing, ensuring that your scripts work predictably and securely, no matter the complexity.

Use set -a only across the smallest controlled section, restore it with set +a, and validate every required variable before starting the application.

Run Java Applications on macOS without a System-Wide JDK

Yoonsoo Park — Wed, 17 Jan 2024 00:00:00 +0000

Introduction

Java’s omnipresence in software development is unquestionable. Yet, installing Java Runtime Environment (JRE) or Java Development Kit (JDK) globally on macOS may invite version clashes or security risks. This guide delves into alternative strategies for executing Java applications (JAR files) on Mac, sidestepping the global JRE setup. We lay particular emphasis on Docker, a celebrated containerization technology.

Costs of a system-wide JDK

Version Conflicts: Diverse Java applications may demand specific Java versions, clashing with a globally installed JRE.
Security Risks: A leaner global software footprint reduces potential vulnerabilities.
Enhanced Portability and Isolation: Containerization assures consistent application performance across varying systems.

Method 1: Application-Enclosed JRE

Encapsulate a JRE within your Java application to dodge system-wide Java conflicts.

Steps:

Acquire a JRE that aligns with your application’s and macOS’s architecture.
Embed the JRE in your application’s folder.
Forge a startup script to designate the encapsulated JRE as JAVA_HOME and initiate your application.

Method 2: A project-local runtime

A portable JRE facilitates Java application execution sans system-wide Java installation.

Steps:

Procure a portable JRE suitable for macOS.
Unpack it in a directory of your choice.
Execute your JAR file using the absolute path to the java command within the portable JRE’s folder.

Method 3: Containerized service execution

Docker offers application execution in insulated settings. Here’s how to use Docker for your JAR file:

1. Docker Installation

Fetch Docker from the official portal and set it up on your Mac.

2. Java Application Preparation

Consolidate your JAR file and all necessary assets in a single folder.

3. Crafting a Dockerfile

In your project folder, craft a Dockerfile with these specifics:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


# Opt for an official Java runtime as the base image
FROM eclipse-temurin:25-jre

# Designate the working area in the container
WORKDIR /usr/app

# Transport current directory's contents into /usr/app in the container
COPY . /usr/app

# Render port 8080 accessible externally
EXPOSE 8080

# Execute the JAR file
ENTRYPOINT ["java", "-jar", "your-application.jar"]

Tweak the port and JAR file name as needed.

4. Docker Image Construction

In your terminal, within the project folder, execute:

1

docker build -t your-app-name .

5. Launching Your Application

Activate your application with:

1

docker run -p 8080:8080 your-app-name

Your Java application is now operational within a Docker container!

Conclusion

Employing macOS to run JAR files sans a global JRE installation is streamlined with the right toolkit. Whether you opt for a bundled JRE, a portable JRE, or Docker’s robust containerization, each avenue offers distinct merits. Containers are useful for services that already have a container deployment target, but they are not the default way to launch a local desktop JAR. For distributable macOS applications, prefer jpackage with a runtime produced by jlink; for development, use a version-managed supported JDK. It eliminates the global JRE dependency while assuring an insulated, controlled application environment.

Mastering the Art of Effective Writing in the Information Era

Yoonsoo Park — Mon, 15 Jan 2024 00:00:00 +0000

The Power of Effective Writing in the Modern World

In an age brimming with media and information, the ability to write effectively has become more crucial than ever. The book “Writing for Busy Readers: Communicate More Effectively in the Real World” by Todd Rogers and Jessica Lasky-Fink emerges as a beacon for those seeking to cut through the noise and reach ‘busy’ readers. This book is not just about writing beautifully; it’s about writing effectively, a skill that has become essential in a world where people are overwhelmed with digital messages.

The Importance of Clarity and Brevity

The book emphasizes the power of brevity and clarity. Just as not everyone who sings is a great singer, not everyone who writes does it exceptionally well. Great singers hone their skills through techniques grounded in anatomy, acoustics, and cognition. Similarly, effective writers must study neuroscience and cognitive science to understand how a busy person’s brain processes written information. This understanding helps in creating content that captures attention amidst the myriad of distractions vying for a reader’s focus.

Six Principles of Effective Writing

Drawing on research in behavioral science, the authors distill their insights into six key principles:

Less is More: Conciseness is key.
Make it Easy to Read: Accessibility in writing is crucial.
Easy Navigation: Organize content for easy reference.
Appropriate Formatting: Use formatting to aid understanding, but avoid excess.
Explain Why it Matters: Make the content relevant and engaging.
Ease of Response: Facilitate a straightforward response from the reader.

These principles are not just theoretical; they are backed by practical examples and real-world applications, making them immediately applicable in various contexts, from emails to business reports.

Beyond Aesthetic Writing

The book draws a distinction between expressive, literary writing and effective writing. While the former is an art form, steeped in subjectivity and emotional depth, the latter is a science-based skill aimed at clear and direct communication. This differentiation is crucial in today’s digital age, where the goal is often to convey specific information quickly and efficiently to busy individuals.

The Practical Benefits of Effective Writing

Effective writing is not just about getting a message across; it also clarifies the writer’s own thoughts. As the book points out, clear writing leads to clear thinking. This clarity is invaluable in our fast-paced world, where misunderstandings can lead to significant time loss and frustration.

Wrapping it up 👏

Alright, wrapping things up here: “Writing for Busy Readers” is pretty much your go-to book if you want to step up your writing game in this crazy-busy world full of info overload. It’s not just about sounding smart or fancy; it’s more about getting your point across effectively, which, let’s face it, is super important these days.

If you’re into getting more details and real-life examples of how to write like a pro, definitely give this book a read. It’s packed with useful tips and tricks that’ll make a big difference in how you communicate, especially online and in the digital space.

Feel like checking it out? Here’s a link to grab a copy and see for yourself: Writing for Busy Readers: Communicate More Effectively in the Real World

Cheers! 🍺

Freeing Up Ports 80 and 443 on Synology NAS for Reverse Proxy Usage

Yoonsoo Park — Sun, 14 Jan 2024 00:00:00 +0000

Freeing Up Ports 80 and 443 on Synology NAS for Reverse Proxy Usage

Introduction

For Synology NAS users looking to implement reverse proxies such as Traefik, Nginx Proxy Manager, or Caddy, the usage of ports 80 and 443 by default NAS services can be a hurdle. These ports, often occupied by the NAS via Nginx, are essential for reverse proxy operations. Fortunately, a Bash script can efficiently reconfigure Nginx, freeing up these crucial ports.

In this article, we explore a Bash script solution for modifying the default HTTP and HTTPS ports on Synology NAS, enabling the use of ports 80 and 443 for other applications.

Understanding the Port Conflict

Synology NAS systems employ Nginx, a widespread web server, in their operating framework. Nginx, by default, listens on ports 80 (HTTP) and 443 (HTTPS). This default setting is suitable for regular operations but creates a conflict for reverse proxy servers that require these same ports.

The Solution: A Bash Script

A Bash script offers a seamless solution to reconfigure the Nginx server on Synology NAS, reallocating ports 80 and 443 for alternate use. Here’s how the script functions:

Script Breakdown

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


#! /bin/bash

# NGINX Ports - CUSTOMIZATION REQUIRED
DEFAULT_HTTP_PORT=80
DEFAULT_HTTPS_PORT=443
NEW_HTTP_PORT=81
NEW_HTTPS_PORT=444

# Modifying Nginx Configuration
sed -i "s/^\([ \t]\+listen[ \t]\+[]:[]*\)$DEFAULT_HTTP_PORT\([^0-9]\)/\1$NEW_HTTP_PORT\2/" /usr/syno/share/nginx/*.mustache
sed -i "s/^\([ \t]\+listen[ \t]\+[]:[]*\)$DEFAULT_HTTPS_PORT\([^0-9]\)/\1$NEW_HTTPS_PORT\2/" /usr/syno/share/nginx/*.mustache

# Restart Nginx to apply changes
synosystemctl restart nginx

Key Aspects of the Script

Customization: Modify NEW_HTTP_PORT and NEW_HTTPS_PORT variables to designate alternative Nginx ports.
Automated Editing: Utilizes sed for replacing default ports in Nginx configuration files.
Restart Nginx: Finalizes with a command to restart Nginx, implementing the adjustments.

Implementation Steps

Create the Script:
- Copy and save the script on your Synology NAS with a .sh extension and execution permissions.
Schedule the Script:
- Set it to run as root at boot through DSM’s Control Panel -> Task Scheduler.
Run and Verify:
- Manually execute or reboot NAS for testing.
- Confirm port changes with tools like netstat.

Points to Remember

DSM Upgrades: Synology’s DSM updates may revert these configurations; hence, scheduling the script is vital.
Port Selection: Choose unused ports on your NAS for the new settings.
Access Control: Update firewall rules and port forwarding accordingly.

Conclusion

This Bash script provides a straightforward and effective way for Synology NAS users to employ reverse proxies by reassigning the default HTTP and HTTPS ports used by Nginx. It’s a practical solution for resolving port conflicts and enhancing the functionality of your NAS. When implementing this script, always ensure to follow network security best practices and check for any service conflicts with the new port assignments.

Adapting and verifying the script based on individual network configurations and Synology NAS models is recommended for optimal results. This approach not only solves the immediate port conflict issue but also opens up new possibilities for using your NAS for diverse applications, from hosting websites to running complex network services.

Cheers! 🍺

Unboxing Leadership - Insights from "Leadership & Self-Deception"

Yoonsoo Park — Sat, 13 Jan 2024 00:00:00 +0000

Introduction

“Leadership & Self-Deception: Getting Out of the Box” by The Arbinger Institute offers transformative guidance in the realms of leadership and personal development, focusing on the impact of self-perception on leadership abilities and interpersonal relations.

Understanding Self-Deception

Self-deception, a core theme of the book, is about having a skewed perception influenced by personal biases and justifications.

Example of Self-Deception

A manager blames his team for missed deadlines, unaware that his poor communication contributes to the issue. This is a classic case of being ‘in the box,’ seeing only from a self-justifying perspective.

Detailed Exploration of Self-Betrayal

The book dives deep into the concept of self-betrayal, an act of going against one’s inherent sense of right, leading to a distorted view of reality.

Acting Against One’s Sense of Right and Wrong: An individual ignores their innate sense of right, like a manager not listening to an employee’s concern due to busyness.
Justification of Actions: The individual justifies their action, like the manager deeming the employee’s issue as unimportant.
Distorted View of Others: This leads to a skewed perception of others, such as viewing the employee as a complainer.
Creation of a Vicious Cycle: This distorted view provokes behaviors that elicit negative responses, reinforcing the distorted perception.
Impact on Relationships and Effectiveness: Such cycles damage relationships and reduce effectiveness, hindering genuine communication and collaboration.
Breaking the Cycle: One must recognize and act contrary to self-betrayal, like a manager genuinely addressing an employee’s concerns.

Key Takeaways with Examples

Being ‘Out of the Box’

Example: A leader sees her employees as unique individuals, adjusting her management style, which enhances morale and productivity.

Resisting the Blame Game

Example: When a project fails, a supervisor reflects on his own shortcomings, leading to positive changes in future project management.

Embracing Vulnerability

Example: A CEO openly shares her challenges, fostering a collaborative and innovative environment.

Prioritizing Relationships

Example: An employee invests in understanding colleagues’ personal goals, enhancing team cooperation.

Leading with Influence, Not Authority

Example: A manager seeks team input and integrates their ideas, increasing commitment and ownership.

Reflecting and Acting

Example: A team leader, upon realizing his bias against certain ideas, consciously works to give equal consideration to all suggestions.

Encouraging Open Communication

Example: Regular open forums in an organization allow for the free expression of concerns, fostering a culture of trust and continuous improvement.

Leadership & Self-Deception: Getting Out of the Box

Cheers! 🍺

Managing Multiple Versions with Pyenv and Virtual Environments

Yoonsoo Park — Mon, 01 Jan 2024 00:00:00 +0000

Managing Multiple Versions with Pyenv and Virtual Environments

When working on multiple projects with different Python versions, it’s crucial to avoid conflicts and ensure that each project uses the correct version and dependencies. This is where virtual environments come in. They are isolated Python environments that let you manage packages and dependencies specific to a project without affecting the global Python installation.

Installing Python Using Homebrew on macOS

Before setting up virtual environments, ensure you have the desired versions of Python installed:

Install Homebrew: Install Homebrew, a package manager for macOS, with the following command: e.g.

1

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Install Python: Use Homebrew to install the latest version of Python:
1

brew install python

Managing Multiple Python Versions with pyenv

Select a release that is still supported on the Python versions page. The concrete version below is an example; pin the version required by the project and use the same value in CI.

pyenv is an indispensable tool for managing multiple Python versions:

Install pyenv: Install pyenv using Homebrew:
1

brew install pyenv
Configure Your Shell: Add the following to your shell configuration file (.bashrc, .zshrc, etc.) and restart your terminal or source the profile:
1 2

eval "$(pyenv init --path)" eval "$(pyenv init -)"
Install Python Versions: Install the desired Python versions:
1

pyenv install 3.13.5
Set Global Python Version: Choose a global Python version with pyenv:
1

pyenv local 3.13.5

Creating and Activating Virtual Environments

Virtual environments are created and activated to isolate project dependencies:

Creating a Virtual Environment: Navigate to your project directory and create a virtual environment:
1

python3 -m venv .venv
Replace .venv with your preferred environment name.
Activating the Virtual Environment: Activate the virtual environment to use it:
1

source .venv/bin/activate
Upon activation, your shell prompt might change to indicate the active environment. Now, the environment’s Python version and packages are isolated from the rest of your system.

How Virtual Environments Set the Correct Python Version and Environment Variables

When a virtual environment is activated:

Python Version: The virtual environment uses the Python version it was created with. Even if you have multiple versions installed on your system, the environment will only have access to and use the specific version it was created with.
Environment Variables: The activation script adjusts environment variables like PATH to ensure that when you invoke python or pip, you’re using the versions installed in the virtual environment’s bin directory. This means any Python scripts you run or packages you install will be confined to the virtual environment.
Isolation: This isolation prevents different projects from interfering with each other’s dependencies. Each virtual environment operates independently, with its own Python binaries and site packages.

Deactivating Virtual Environments

To stop using a virtual environment and revert to your global Python setup, simply run:

1

deactivate

Your shell’s prompt will return to normal, and you’ll be using the global Python version and packages again.

How to Uninstall Salesforce CLI from a Specific Node.js Version on macOS

Yoonsoo Park — Fri, 01 Dec 2023 01:25:00 -0400

Identify the active installation

Node version managers give each Node.js version its own global npm directory. Before removing anything, determine whether the active sf executable came from npm or Salesforce’s native installer.

1
2
3
4
5


type -a sf
command -v sf
sf version --verbose
npm prefix --global
npm list --global --depth=0 @salesforce/cli sfdx-cli

If command -v sf points outside the reported npm prefix, changing npm packages will not remove that executable.

Remove only the package owned by this Node version

The supported npm package is @salesforce/cli; sfdx-cli is legacy. Switch to the intended Node version, confirm its prefix again, and uninstall the package it owns:

1
2
3
4
5


npm uninstall --global @salesforce/cli
# If the listing showed the retired package:
npm uninstall --global sfdx-cli
hash -r
type -a sf

Do not manually delete whichever file which returns, and do not remove ~/.sfdx or other CLI state directories. Those actions bypass the package owner and can destroy authorization or configuration unrelated to this Node version.

If another sf remains in type -a, identify its owner before deciding whether it should stay. A native installer is a good workstation default because it does not move when nvm changes Node versions; npm is reasonable when the team deliberately manages global tools per Node version.

Verify removal in a fresh shell. If you intend to keep Salesforce CLI, install one supported distribution and run sf doctor plus a read-only command against a nonproduction org. Reviewed on 2026-08-01 against Install Salesforce CLI.

Domain-Driven Design Practices and Pitfalls

Yoonsoo Park — Thu, 30 Nov 2023 01:25:00 -0400

Navigating the World of DDD: Do’s and Don’ts

Domain-Driven Design is most useful when a team applies it to real domain complexity rather than adopting its vocabulary as an architecture template. The following practices keep modeling connected to business behavior.

DDD: The Do’s

1. Embrace Ubiquitous Language

Do: Develop a common language that’s understood by all team members, regardless of their technical background. This ensures that everyone is on the same page and reduces misunderstandings.
Don’t: Allow jargon or technical terms to dominate discussions, as this can alienate non-technical stakeholders and create barriers.

2. Focus on the Domain Model

Do: Invest time in creating a robust and accurate domain model that reflects the business’s needs and realities. This model should be the heart of your project.
Don’t: Rush the modeling process or overlook the nuances of the business domain. An oversimplified or inaccurate model can lead to flawed software design.

3. Utilize Bounded Contexts

Do: Clearly define and respect the boundaries of each context within your domain. This helps in managing complexity and maintaining focus.
Don’t: Ignore the boundaries between contexts or allow them to become blurred, as this can lead to a tangled, hard-to-maintain codebase.

4. Engage in Continuous Learning

Do: Encourage ongoing learning and collaboration among team members. DDD is as much about people and processes as it is about technology.
Don’t: Become complacent or stop evolving your understanding of the domain. DDD requires a mindset of continuous improvement.

DDD: The Don’ts

1. Avoid Over-Engineering

Do: Keep solutions as simple and as relevant to the domain as possible.
Don’t: Overcomplicate your design with unnecessary patterns or technologies that don’t serve the domain’s needs.

2. Beware of Siloed Knowledge

Do: Foster a culture of shared knowledge and collaboration.
Don’t: Allow knowledge to become siloed within specific individuals or teams. This can create bottlenecks and dependencies.

3. Resist the One-Size-Fits-All Approach

Do: Tailor your approach to the specific needs and nuances of each project.
Don’t: Apply DDD principles rigidly or dogmatically. What works for one project may not work for another.

4. Don’t Ignore Non-Technical Stakeholders

Do: Involve business experts and other non-technical stakeholders actively in the process.
Don’t: Develop in isolation from the rest of the business. DDD is a collaborative approach that requires input from all sides.

Wrapping Up

Domain-Driven Design is a powerful methodology that, when used wisely, can greatly enhance your software development projects. By following these do’s and don’ts, you can avoid common pitfalls and leverage DDD to its fullest potential.

DDD is not primarily a code organization scheme. Its value comes from improving the model and shared language used to solve business problems.

Eric Evans’s “Domain-Driven Design: Tackling Complexity in the Heart of Software” remains a useful primary reference for teams that need the strategic and tactical concepts in more depth.

Deep Dive into Domain-Driven Design - Simplifying Complex Projects

Yoonsoo Park — Wed, 29 Nov 2023 01:25:00 -0400

Introduction

Domain-Driven Design (DDD) helps teams model software around a complex business domain. Domain Storytelling is one collaborative technique for learning how people, processes, and systems interact before committing to a model.

The Prelude: The Need for DDD

A requirements list without the surrounding business rules, language, and constraints can produce a technically correct implementation of the wrong model. DDD addresses that risk through sustained collaboration with domain experts.

Understanding Domain-Driven Design

DDD is not just a set of practices; it’s a philosophy that puts the project’s domain at the heart of every decision. Here’s what it entails:

Ubiquitous Language: This is the cornerstone of DDD. It’s about creating a common language that’s shared among all stakeholders, from developers to business analysts. This language is used to describe all aspects of the project, ensuring clear communication and understanding.
Model-Driven Design: In DDD, the focus is on creating a robust domain model that accurately represents the business domain. This model guides the design of the software, ensuring that it aligns with the business needs.
Bounded Contexts: DDD divides the domain into multiple bounded contexts, each representing a distinct part of the domain with its own model. This helps in managing complexity by isolating different parts of the domain.
Context Mapping: Understanding how these bounded contexts interact with each other is crucial. Context mapping helps in identifying and managing these relationships, ensuring that the overall system remains cohesive.

Domain Storytelling

Domain Storytelling captures concrete work scenarios in a visual, shared form. It supports discovery; it does not replace bounded-context design or validation with the people doing the work.

Crafting the Story:

Inclusive Gatherings: Bring together all stakeholders, ensuring everyone’s voice is heard.
Narrative Over Diagrams: Use simple, relatable stories to describe user interactions, avoiding technical complexities.

The Art of Pictographic Language:

Simple Elements: Use symbols like actors, work objects, actions, and sequence numbers to depict the story.
Guiding Principles: Avoid repeating actors, focus on scenarios, and consider the scope in terms of granularity and digital versus physical interactions.

Applying DDD; The Scenario: Car Purchase Journey

Imagine a scenario where a customer is looking to purchase a car on installments. This process involves several steps and stakeholders, making it an ideal candidate for applying DDD.

Step 1: Understanding the Domain

Identify Key Entities: Our domain involves entities like Customer, Car, Salesperson, Finance Agreement, etc.
Develop Ubiquitous Language: Establish common terms understood by all stakeholders. For example, “Finance Agreement” is a term everyone understands the same way.

Step 2: Creating the Domain Model

Model the Entities and Their Relationships: Map out how these entities interact. For example, a Customer chooses a Car, interacts with a Salesperson, and signs a Finance Agreement.
Focus on Business Logic: The domain model should capture the logic and rules of the car purchasing process, such as credit checks, payment plans, etc.

Step 3: Implementing Bounded Contexts

Define Contexts: Break down the domain into manageable contexts, like “Sales,” “Finance,” and “Inventory.”
Context Interactions: Understand how these contexts interact. For instance, “Sales” may initiate a credit check process in “Finance.”

Engage Stakeholders: Regularly consult with salespeople, finance officers, and customers to refine the model and understand their needs.
Iterate the Model: Continuously refine the model based on feedback and new insights.

Step 5: Translating to Code

Implementing Entities and Relationships: Translate the domain model into code, creating classes, and methods that reflect the real-world entities and processes.
Building the User Interface: Design the UI to align with the domain model, ensuring it’s intuitive for users, like having a clear flow from car selection to financing.

Step 6: Leveraging Domain Storytelling

Narrate the Customer’s Journey: Use Domain Storytelling to depict the customer’s experience, from entering the dealership to driving away with the car.
Visualize with Pictographic Language: Create diagrams that represent the steps in the process, such as selecting a car, discussing with a salesperson, and signing documents.

Wrapping Up: Embracing DDD for Better Collaboration

DDD, coupled with Domain Storytelling, is not just a method; it’s a mindset shift. It brings clarity, efficiency, and a user-centric focus to software development. It’s a way to make the development process more enjoyable and inclusive for everyone involved.

Further Exploration

To delve deeper, check out “Domain Storytelling: A Collaborative, Visual, and Agile Way to Build Domain-Driven Software” and visit domainstorytelling.org.

The companion article covers practical DDD practices and pitfalls.

Use DDD where domain complexity justifies the modeling investment. A simple data-entry application may not need the full strategic and tactical pattern set.

Solving SSH Connection Issues on macOS - A Guide to Fixing 'Unprotected Private Key File' Error

Yoonsoo Park — Tue, 28 Nov 2023 01:25:00 -0400

Solving SSH Connection Issues on macOS: A Guide to Fixing ‘Unprotected Private Key File’ Error

When working with AWS EC2 instances, particularly from a macOS environment, a common hurdle that many face is the Unprotected Private Key File error during SSH connections. This error can halt your workflow, preventing access to your remote servers. Understanding and resolving this error is crucial for maintaining a secure and efficient development environment.

Understanding the Error

The error typically reads:

@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
@ WARNING: UNPROTECTED PRIVATE KEY FILE! @
@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
Permissions 0644 for 'ec2-demo.pem' are too open.
It is required that your private key files are NOT accessible by others.
This private key will be ignored.
Load key "ec2-demo.pem": bad permissions
ec2-user@3.8x.6x.1xx: Permission denied (publickey,gssapi-keyex,gssapi-with-mic).

This error occurs because the SSH protocol requires that your private key files are kept secure and not accessible by other users on your system. The recommended permissions for these files are 600, allowing only the file’s owner to read and write.

The Solution

Step 1: Open Terminal

Launch the Terminal application on your macOS. This is where you’ll execute commands to modify file permissions.

Step 2: Navigate to the Key File

Use the cd command to navigate to the directory containing your .pem file. For example:

1

cd /path/to/your/key

Replace /path/to/your/key with the actual path to your .pem file.

Step 3: Change File Permissions

Once in the correct directory, run:

1

chmod 600 ec2-demo.pem

This command changes the file permissions to 600, restricting access to only the file’s owner.

Step 4: Retry SSH Connection

After updating the permissions, connect to your EC2 instance:

1

ssh -i /path/to/ec2-demo.pem ec2-user@3.8x.6x.1xx

Replace /path/to/ with the actual path to your .pem file.

How to Rename a Git Branch Using the CLI

Yoonsoo Park — Mon, 30 Oct 2023 01:25:00 -0400

Introduction

Renaming a Git branch may seem like a trivial task, but it can become complex, especially when you’ve already pushed the branch to a remote repository. In this blog post, we’ll go through the steps to rename a local and remote Git branch using the Command-Line Interface (CLI).

Step 1: Switch to the Branch You Want to Rename

Before you can rename a branch, you need to switch to it. Open your terminal and run the following command:

1

git switch old-branch-name

Step 2: Rename the Local Branch

Once you’re on the branch you wish to rename, use the following command to rename it:

1

git branch -m new-branch-name

The -m flag stands for “move,” which effectively renames the branch.

Step 3: Update the Remote Branch

If you have already pushed the branch to a remote repository and you wish to rename it there as well, you’ll need to delete the old branch and then push the new one. Here’s how you do it:

1
2


git push origin --delete old-branch-name
git push origin -u new-branch-name

The -u flag sets the upstream, so future git pull and git push commands on this branch will automatically know which remote branch to interact with.

Step 4: Update Any Open Pull Requests

GitHub does not let you retarget an existing pull request to an arbitrary renamed head branch. Check the pull request state before deleting the old remote branch; you may need to keep it or open a replacement PR.

If you have any open pull requests that involve the old branch name, remember to update those manually to point to the new branch name.

Step 5: Inform Your Team Members

Renaming a remote branch is a significant change that can affect all team members who are using the same repository. It’s good practice to inform everyone about the change. Team members can update their local branches with the following commands:

1
2
3
4


git branch -m old-branch-name new-branch-name
git fetch origin
git branch --unset-upstream
git branch -u origin/new-branch-name

How to Clean Up Inaccessible Scratch Org Authorizations

Yoonsoo Park — Tue, 12 Sep 2023 01:25:00 -0400

Introduction

An expired or already-deleted scratch org can leave a stale local authorization. Use supported CLI commands to diagnose and remove it; don’t edit Salesforce CLI’s internal files by hand.

Identifying the Problem

Start with sf org list auth and sf org display --target-org <alias>. If display fails because the remote org no longer exists, remove only the local authorization.

Symptoms:

Running sfdx force:org:list displays the problematic scratch org.

force-nforce-003jsL test-ry0x7ndfdivv@example.com 00D040000003jsLEAQ DomainNotFoundError

Attempting to delete the org results in an error.

ERROR running force:org:delete: The org cannot be found

Supported cleanup flow

1
2


sf org list auth
sf org logout --target-org stale-alias

If the scratch org still exists and you intend to dispose of it, use sf org delete scratch --target-org <alias> instead. This updates the Dev Hub as well as local state.

Reauthenticate only when the org still exists

If the org still exists on the Salesforce server, sometimes re-authenticating can resolve these issues.

1

sf org login web --instance-url https://test.salesforce.com --alias my-scratch

After re-authenticating, try to delete the org again.

Move the project default

Set another default org to potentially resolve some edge cases.

1

sf config set target-org=my-new-default

Do not edit ~/.sfdx/orgs.json or other internal state: storage formats change, and hand edits can corrupt unrelated authorizations. If supported logout fails, run sf doctor, preserve its sanitized diagnostics, and use Salesforce CLI support guidance. Reviewed against the org command reference on 2026-08-01.

Safely Update Python Project Dependencies

Yoonsoo Park — Fri, 08 Sep 2023 01:25:00 -0400

A Python environment is an installation result, not necessarily the project’s dependency policy. Bulk-upgrading every installed distribution mixes direct requirements with transitive packages and can produce a combination nobody reviewed. A safer workflow starts from declared intent, resolves a reproducible result, and proves that the application still works.

This guide was verified on 2026-08-01 against the Python Packaging User Guide, pip’s pip install and pip check documentation, and the PyPA reproducible-environments specifications.

Understand the three layers

Declared dependencies describe what the project intentionally needs. They may live in pyproject.toml, requirements.in, or another tool’s project file.
Resolved dependencies select exact compatible versions, often in a lock file or compiled requirements file.
Installed environment is one realization of that resolution for a Python version and platform.

pip freeze reports installed distributions. It cannot reliably tell which packages are direct requirements or why they were selected. That makes it useful for diagnostics and some environment snapshots, but a poor substitute for a maintained project declaration.

A safe update loop

Begin in a clean branch and an isolated environment:

1
2
3
4


python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip list --outdated

Choose a small update scope. Read the direct dependency’s release notes, supported Python versions, and migration guidance. Update the declaration using the project’s existing tool, regenerate its lock or compiled requirements output, and inspect the diff before installing it.

For a requirements workflow using pip-tools, that might look like:

1
2
3


python -m pip install pip-tools
pip-compile --upgrade-package requests requirements.in
pip-sync requirements.txt

For a standards-based pyproject.toml project, use the repository’s selected resolver or workflow tool. Do not introduce a second lock format merely because another tool is popular. Libraries and deployable applications also have different needs: libraries normally declare compatible ranges, while applications often lock a complete environment for repeatable deployment.

Security updates and automation

Automated dependency pull requests from Dependabot or Renovate reduce detection time, but they do not remove the need for review. Keep batches small enough to attribute failures. Confirm that package names and download indexes are expected, especially when adding a dependency for the first time.

A vulnerability report is a prioritization input, not permission to ignore compatibility. Check whether the vulnerable component is reachable in this project, whether a patched compatible version exists, and whether a mitigation is needed while an upgrade is tested. Never paste private lockfiles, index credentials, or internal package names into a public analysis service.

Alternatives and tradeoffs

venv plus pip is the minimal standard baseline but does not provide a universal lock workflow by itself.
pip-tools compiles reviewed inputs into pinned requirements and fits many existing pip deployments.
Poetry, PDM, Hatch, Pipenv, and uv combine different portions of environment, resolution, build, and task management. Choose based on repository requirements and CI support rather than declaring one universal winner.
pipx is for installing standalone Python applications, not project libraries.

Changing tools is a migration project. Preserve the old declaration until the new resolver produces an accepted environment on every supported platform.

Migration from a frozen environment

Save the current file as evidence; do not immediately treat every line as a direct requirement.
Identify imports, entry points, runtime services, and explicitly chosen packages.
Build a minimal direct-dependency declaration with justified version bounds.
Resolve it in a fresh environment and compare behavior with the old environment.
Add platform markers and optional dependency groups where they express real differences.
Adopt one lock or compiled-output convention and document its update command.
Remove the old snapshot only after CI and deployment validation pass.

Verification gate

1
2


python -m pip check
python -m pytest

Also run the application’s normal type checks, linting, build, smoke test, and production-like startup. Recreate the environment from scratch in CI rather than trusting a long-lived local environment. Review the declaration and resolved-file diff together; an unexplained transitive jump is a reason to stop and investigate.

Record the update date, direct package changed, source release notes, supported Python range, test evidence, and rollback method in the pull request. For services, observe error rate, latency, and startup behavior during a staged rollout. For libraries, test the lowest and highest supported dependency ranges where practical. A successful local import is useful evidence, but it is not a substitute for the consumer-facing compatibility gate.

Salesforce Source Format, Conversion, and Deployment

Yoonsoo Park — Wed, 06 Sep 2023 01:25:00 -0400

This guide was verified against Salesforce’s current CLI reference on 2026-08-01.

Why the old conversion-first flow changed

Salesforce DX source format splits large Metadata API files into smaller files that work better in Git. Older workflows often converted that source into Metadata API format before every deployment. Current Salesforce CLI deploys project source directly, including to sandboxes and production orgs. Conversion remains supported, but it is an interoperability tool rather than a required deployment stage.

The old sfdx force:source:convert command is also part of the unsupported sfdx CLI. Keeping it in a build adds an intermediate artifact, extra file-selection logic, and an opportunity for the converted package to drift from the reviewed source.

Current mental model

Keep the repository in source format. Use sf project deploy start for delivery and sf project retrieve start for deliberate retrieval. Convert only at a boundary where another tool or process explicitly requires Metadata API format.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


# See what the CLI intends to deploy.
sf project deploy preview --source-dir force-app --target-org staging

# Validate without committing the deployment.
sf project deploy start --source-dir force-app --target-org staging \
 --dry-run --test-level RunLocalTests

# Deploy the same reviewed scope.
sf project deploy start --source-dir force-app --target-org staging \
 --test-level RunLocalTests

Use a manifest when release scope is curated independently of a directory:

1
2


sf project deploy start --manifest manifest/package.xml \
 --target-org staging --dry-run

Always inspect the preview, identify destructive changes separately, and choose a test level appropriate to the target. Authentication belongs in the workstation keychain or CI secret store, not in the repository.

When conversion is appropriate

Convert source format to Metadata API format when a downstream system accepts a package.xml bundle and cannot consume a Salesforce DX project:

1
2


sf project convert source --root-dir force-app \
 --output-dir build/mdapi --package-name ReleaseBundle

Convert a received Metadata API package into source format before maintaining it in Git:

1
2


sf project convert mdapi --root-dir incoming/unpackaged \
 --output-dir force-app

Conversion is useful for legacy integrations, package inspection, and migrations. Its costs are duplicated artifacts and lossy-looking structural changes: a single object file can become many source files, and recomposition can make diffs hard to reason about. Treat generated output as ephemeral and rebuild it from reviewed source.

Migration checklist

Find sfdx force:source:convert, mdapi:deploy, and committed converted directories.
Confirm whether any downstream consumer truly requires Metadata API format.
Replace ordinary delivery with sf project deploy preview and sf project deploy start --dry-run.
Preserve manifests when they express intentional release scope.
If conversion remains necessary, write to a clean build directory and never edit both representations.
Test retrieval and deployment in a disposable org, including decomposed metadata such as Custom Objects.
Run the project test suite and compare the deployed component set before changing production automation.

Verification

A successful command is not enough. Confirm that preview selected the expected components, validation ran the intended tests, the target org is explicit, and Git contains only the source representation. In CI, pin the CLI version and archive deployment reports rather than converted secrets or auth material.

Official sources

Initializing a Python Project in Visual Studio Code

Yoonsoo Park — Thu, 31 Aug 2023 01:25:00 -0400

Current VS Code environment workflow

VS Code now provides a Python Environments workflow that discovers .venv, pyenv, conda, Poetry, Pipenv, and uv environments. Prefer .venv, python -m pip, a declared project dependency file, and the repository default branch instead of assuming a global interpreter or master.

Initializing a Python Project in Visual Studio Code

Creating a Python project involves more than just writing code. It entails setting up an organized file structure, managing dependencies, and even integrating version control for collaborative development. In this article, we’ll go through the steps to initialize a Python project in VS Code, install the necessary dependencies, and set up a GitHub repository for version control.

Step 1: Create a New Folder in VS Code

Open Visual Studio Code and create a new folder for your Python project using the “New Folder” button. This folder will be the root directory of your Python project.

Step 2: Initialize a Virtual Environment

Open the terminal in VS Code by navigating to View > Terminal or pressing Ctrl+~.
Run the following command to create a virtual environment. Replace myenv with your desired name.
1

python -m venv myenv

Step 3: Activate the Virtual Environment

Activate your virtual environment by running:

On Windows:
1

.\myenv\Scripts\Activate
On macOS and Linux:
1

source myenv/bin/activate

Step 4: Install Required Packages

Install the required Python packages by running the following command:

1

pip install requests google_images_search

Step 5: Create Python Files

Create a new Python file (main.py, for example) and paste your Python code into it.

Initialize GitHub Repository

Step 1: Initialize Local Repository

In the terminal, run:

1

git init

Step 2: Create `.gitignore` File

Create a .gitignore file and add the following:

1
2
3
4


myenv/
__pycache__/
*.pyc
*.pyo

Step 3: Add and Commit Files

Run the following commands to add and commit your files locally:

1
2


git add .
git commit -m "Initial commit"

Step 4: Create a GitHub Repository

Step 5: Link Local Repository to GitHub

Replace your-repo-url with the URL of your GitHub repository and run:

1

git remote add origin your-repo-url

Step 6: Push to GitHub

Push your local commits to the GitHub repository:

1

git push -u origin master

Passing Command-Line Arguments to a TypeScript Script using NPM

Yoonsoo Park — Fri, 18 Aug 2023 01:25:00 -0400

Argument boundary and validation

npm run script -- arg1 arg2 remains the portable argument boundary. Use the project-pinned TypeScript runner or compiled JavaScript, validate process.argv with a maintained parser for nontrivial CLIs, and return a nonzero exit code for invalid input.

Introduction

In modern JavaScript and TypeScript development, npm scripts are commonly used to streamline and simplify various tasks. However, there may be occasions when you need to pass arguments to these scripts to make them more dynamic. In this article, we’ll explore how to pass command-line arguments to a TypeScript script using npm run.

Setting up NPM to Run Your TypeScript Script

To run your TypeScript script using the npm run command, you can define a script in your package.json file. Here’s a step-by-step guide to help you set it up:

Ensure you have the necessary dependencies. Before running TypeScript files, make sure you have the TypeScript compiler and, optionally, ts-node installed.
Create or update a tsconfig.json file to include compiler options for TypeScript.
Add a script entry to the scripts section of your package.json to execute the TypeScript file with ts-node.

Passing Parameters with NPM Run

Handling Arguments in TypeScript:

In your TypeScript script, Node.js provides a global object called process.argv which is an array containing the command-line arguments passed when the process was launched. The first two values are the node executable and your script’s path, so you’ll usually want to access the arguments starting from index 2:
1

const args = process.argv.slice(2);
For our use case, we want to retrieve the arg argument:
1 2

const profileArg = args.find((arg) => arg.startsWith("--arg=")); const profileName = profileArg ? profileArg.split("=")[1] : "default";
Updating the NPM Script:

Your package.json file remains unchanged. It can look like this:
1 2 3

"scripts": { "start": "ts-node your-script-file.ts" }
Executing the Script with Arguments:

When running your script, use the following format to pass in the arg argument:
```
npm run start -- --arg=myProfile
```
The -- after npm run start indicates that the subsequent arguments should be passed directly to the invoked script.

Advanced: Using Argument Parsers

For more advanced command-line argument parsing, consider using libraries like yargs or commander. They offer a plethora of features such as default values, required arguments, aliases, and much more, which can make your scripts more robust and user-friendly.

Conclusion

Passing command-line arguments to your TypeScript scripts via npm run can greatly enhance their flexibility. Whether you’re looking to provide different configurations, paths, or any other kind of data, this method can simplify and streamline your development process.

Using Git Stash to Save and Restore Work in Progress

Yoonsoo Park — Mon, 31 Jul 2023 01:25:00 -0400

Introduction

git stash is one of those Git commands that can be an absolute lifesaver when you’re in the middle of a coding session. Imagine you’re working on a new feature and suddenly need to switch context—perhaps to a different branch to work on a hotfix. You don’t want to commit half-baked code, but you need to save your changes somewhere. Enter git stash.

In this article, we’ll explore various ways to use git stash to your advantage, helping you to save, manage, and restore your code changes effectively.

Basic Stashing

Saving Changes

The basic form of the git stash command is straightforward. Simply run:

1

git stash

This command takes your modified tracked files and stages them along with any new files you’ve indicated with git add, and stashes them away for later use.

Listing Stashes

You can view all your stashes using:

1

git stash list

This command will show you a list of all the stashes that you’ve created, making it easier to manage them.

Advanced Stashing Techniques

Applying the Latest Stash

You can apply the changes from the most recent stash using:

1

git stash apply

This command will keep the stash, allowing you to apply the same changes to multiple branches.

Popping the Latest Stash

Alternatively, you can use:

1

git stash pop

This will apply the stashed changes and remove them from your stash list.

Dropping a Stash

If you want to discard a stash, you can use:

1

git stash drop stash@{0}

This command will remove the specified stash from your stash list.

Applying a Specific Stash

If you’ve created multiple stashes, you can specify which stash to apply:

1

git stash apply stash@{1}

Or, if you wish to apply and remove it from the stash list:

1

git stash pop stash@{1}

Handling Conflicts

Just like with merges or rebases, conflicts can occur when you apply or pop a stash. You’ll have to resolve these conflicts manually before you can continue your work.

Conclusion

git stash temporarily records tracked changes when a short-lived clean working tree is useful. It is not a durable substitute for a branch or commit. Inspect the stash before applying it and retain it until any conflicts are resolved.

So the next time you find yourself needing to switch tasks but don’t want to lose your changes, remember: just stash it!

Checking Object Type in TypeScript

Yoonsoo Park — Wed, 05 Jul 2023 01:25:00 -0400

When working with TypeScript, it’s often necessary to determine the type of a variable. In particular, you might need to check whether a variable is of object type. Fortunately, TypeScript provides a straightforward way to perform this type check.

The `typeof` Operator

In TypeScript, you can use the typeof operator to check the type of a variable. To determine if a variable is of object type, combine typeof with the object keyword.

Here’s an example:

1
2
3
4
5
6
7


const variable: any = {}; // Your variable

if (typeof variable === 'object' && variable !== null) {
 console.log('The variable is an object.');
} else {
 console.log('The variable is not an object.');
}

In this code snippet, the typeof variable === 'object' condition checks whether the type of variable is an object. Additionally, variable !== null ensures that null is not considered an object.

Specifying a Specific Object Type

If you’re looking to check for a specific object type, you can replace the any type in the variable declaration with the desired type.

Here’s an example:

1
2
3
4
5
6
7


const variable: SomeObjectType = {}; // Your variable of type SomeObjectType

if (typeof variable === 'object' && variable !== null) {
 console.log('The variable is an object of type SomeObjectType.');
} else {
 console.log('The variable is not an object of type SomeObjectType.');
}

Replace SomeObjectType with the actual type you’re expecting for your variable.

Conclusion

Checking the object type in TypeScript is essential when you want to ensure the correctness of your code. By using the typeof operator in combination with the object keyword, you can easily determine whether a variable is an object. If you’re looking for a specific object type, replace the any type with the desired type in the variable declaration.

Creating Zip Files from JSON Configuration with Node.js and TypeScript

Yoonsoo Park — Mon, 03 Jul 2023 01:25:00 -0400

Trust boundaries and archive paths

do not use this example with untrusted JSON. Constrain every resolved input to an approved root, reject missing files and symbolic-link escapes, generate relative archive entry names, use a unique output path, and await both archive and output-stream failures. The original synchronous sample is suitable only for small, trusted local input after those controls are added.

In this article, we’ll explore a practical use case involving JSON parsing and file operations in Node.js and TypeScript. Specifically, we’ll write a script to read a JSON configuration file, extract files and directories specified therein, and zip them into a single file.

Prerequisites

Before we get started, make sure you have Node.js and TypeScript installed on your system. Also, you will need the fs, path and archiver libraries. If you haven’t installed the archiver library yet, you can add it to your project using npm:

1

npm install archiver

The Code

Let’s look at the TypeScript script.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87


import * as fs from 'fs';
import * as path from 'path';
import * as archiver from 'archiver';

function getAllFiles(root: string, dirPath: string, arrayOfFiles: string[] = []) {
 const files = fs.readdirSync(dirPath);

 files.forEach(function(file) {
 const candidate = path.join(dirPath, file);
 const stat = fs.lstatSync(candidate);
 if (stat.isSymbolicLink()) {
 throw new Error(`Symbolic links are not allowed: ${candidate}`);
 }
 if (stat.isDirectory()) {
 arrayOfFiles = getAllFiles(root, candidate, arrayOfFiles);
 } else {
 arrayOfFiles.push(candidate);
 }
 });

 return arrayOfFiles;
}

function resolveInside(root: string, input: string): string {
 const resolved = path.resolve(root, input);
 const relative = path.relative(root, resolved);
 if (relative.startsWith("..") || path.isAbsolute(relative)) {
 throw new Error(`Path escapes the approved root: ${input}`);
 }
 return resolved;
}

async function main() {
 const approvedRoot = path.resolve("input-files");
 const rawData = fs.readFileSync('input.json');
 const jsonData: unknown = JSON.parse(rawData.toString());

 if (
 typeof jsonData !== "object" ||
 jsonData === null ||
 !("configuration" in jsonData) ||
 typeof jsonData.configuration !== "object" ||
 jsonData.configuration === null
 ) {
 throw new Error("Invalid configuration object");
 }

 const output = fs.createWriteStream('output.zip');
 const archive = archiver('zip', {
 zlib: { level: 9 } // Sets the compression level.
 });

 output.on('close', () => console.log(archive.pointer() + ' total bytes'));
 archive.on('error', (err: any) => { throw err; });
 archive.pipe(output);

 for (const entries of Object.values(jsonData.configuration)) {
 if (!Array.isArray(entries) || !entries.every(value => typeof value === "string")) {
 throw new Error("Every configuration value must be an array of paths");
 }
 for (const configuredPath of entries) {
 const fileOrFolder = resolveInside(approvedRoot, configuredPath);
 const stat = fs.lstatSync(fileOrFolder);
 if (stat.isSymbolicLink()) throw new Error(`Symbolic links are not allowed: ${configuredPath}`);
 const isDirectory = stat.isDirectory();

 if (isDirectory) {
 const files = getAllFiles(approvedRoot, fileOrFolder);

 for(const file of files) {
 const filePath = path.resolve(file);
 archive.append(fs.createReadStream(filePath), {
 name: path.relative(approvedRoot, filePath),
 });
 }
 } else {
 archive.append(fs.createReadStream(fileOrFolder), {
 name: path.relative(approvedRoot, fileOrFolder),
 });
 }
 }
 }

 await archive.finalize();
}

main().catch(console.error);

How it works

The script parses JSON as unknown and validates the expected object and path-array shape before using it. Each configured path is resolved relative to input-files; resolveInside rejects traversal outside that root.

It then creates a write stream for the output zip file and sets up the archiver to zip files.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


const output = fs.createWriteStream('output.zip');
const archive = archiver('zip', {
 zlib: { level: 9 } // Sets the compression level.
});

output.on('close', () => console.log(archive.pointer() + ' total bytes'));
archive.on('error',

(err: any) => { throw err; });
archive.pipe(output);

The traversal uses lstat and rejects symbolic links. Archive entry names come from path.relative(approvedRoot, filePath), so they do not expose absolute host paths. The synchronous directory calls keep this local example compact; a service should use asynchronous traversal with bounded concurrency.

Once all files have been processed, it finalizes the archive, effectively creating the zip file.

1

await archive.finalize();

Also listen for errors from both the archive and output streams in production, create the destination atomically, and apply file-count and size limits before accepting untrusted workloads.

Conclusion

Node.js can automate archive creation, but filesystem input needs an explicit trust boundary. Before using this pattern outside a controlled local script, validate roots and entry names, handle stream failures, and test extraction with representative nested paths.

Remember to handle file and directory paths carefully and ensure that your script has appropriate permissions to read and write where necessary.

Query S3 Buckets Safely with the AWS CLI and JMESPath

Yoonsoo Park — Mon, 26 Jun 2023 01:25:00 -0400

aws s3api list-buckets lists general-purpose buckets owned by the authenticated account. AWS CLI’s --query option uses JMESPath and can both project fields and filter by values. An older version of this article incorrectly said value filtering required jq or grep.

First verify the identity, especially when several profiles are configured:

1

aws sts get-caller-identity --profile engineering-dev

List bucket names:

1
2
3
4


aws s3api list-buckets \
 --profile engineering-dev \
 --query 'Buckets[].Name' \
 --output text

Filter for an exact name in JMESPath:

1
2
3
4


aws s3api list-buckets \
 --profile engineering-dev \
 --query "Buckets[?Name=='example-bucket'].Name" \
 --output text

For automation, an empty text result is ambiguous unless the script checks it explicitly. Avoid piping to unanchored grep, where logs could accidentally match logs-archive and output formatting can change.

Listing is not always the right check

If the application already knows the bucket name and needs to determine whether its current identity can address it, use head-bucket:

1
2
3
4
5
6
7
8


if aws s3api head-bucket \
 --bucket example-bucket \
 --profile engineering-dev 2>/dev/null; then
 echo "bucket is reachable"
else
 echo "bucket is missing or access is denied" >&2
 exit 1
fi

For security reasons, error details may not always distinguish a nonexistent bucket from one the caller cannot access. Do not turn that ambiguity into a false “does not exist” claim. Creating a bucket based only on a failed head request can race or target the wrong account.

Pagination and scale

Current ListBuckets supports pagination and optional prefix/Region parameters. AWS strongly recommends paginated requests; unpaginated requests are rejected for accounts with an approved general-purpose bucket quota above 10,000. AWS CLI paginates by default, but scripts that set --no-paginate or call the API directly must handle this deliberately. Directory buckets are not returned by this operation.

Examples:

1
2


aws s3api list-buckets --prefix team-a- --max-items 100
aws s3api list-buckets --bucket-region us-east-1 --max-items 100

The exact CLI JSON skeleton is not a stable programmatic contract. For application logic, use an AWS SDK paginator and typed response rather than parsing human-oriented text output.

Verification checklist

Confirm account and role with STS.
Test exact match, no match, and names with similar prefixes.
Test access denied separately from an absent name.
Preserve pagination in large-account scripts.
Grant only s3:ListAllMyBuckets or specific bucket actions actually required.
Do not print sensitive account inventories into shared CI logs.

Official documentation reviewed on 2026-08-01:

Fish Shell for Interactive Development

Yoonsoo Park — Sun, 25 Jun 2023 01:25:00 -0400

The command-line interface (CLI) remains an integral tool in every developer’s toolkit. It allows developers to interact with the operating system and perform tasks such as file manipulation, process control, and even software development. Bash has long been the default shell for most Linux distributions and macOS. However, there is an alternative gaining popularity - the Friendly Interactive Shell, also known as Fish.

Fish is a modern and user-friendly command-line shell designed to provide a rich scripting environment, out-of-the-box intelligent features, and a visually appealing interface. Here are some reasons why developers are embracing Fish shell as their new command-line partner.

1. Intelligent Autocompletion

One of Fish’s most praised features is its intelligent and robust autocomplete functionality. Unlike Bash, Fish can suggest commands based on the user’s history and often-used commands. Fish even completes commands based on man page entries, making it easier to use and learn new commands.

2. Syntax Highlighting

Fish shell provides syntax highlighting right on the command line, an uncommon feature for shells. Incorrect commands are highlighted in red, making it easier to spot mistakes. Valid file paths, on the other hand, are highlighted in a different color, providing quick visual feedback.

3. Web-Based Configuration

Fish includes a web-based configuration system, known as Fish Config. This allows for a graphical user interface to change shell appearance, variables, and functions without the need for text-based configuration files.

4. Improved Scripting

Fish offers a more straightforward scripting syntax than other shells like Bash. Its syntax is designed to be simpler and more consistent, reducing the complexity involved in writing shell scripts.

5. Excellent Documentation

Fish boasts an extensive and well-structured documentation, accessible directly through the command line with the help command. This makes learning Fish and troubleshooting issues a breeze.

6. Event Handling

Fish supports event handling mechanism that triggers functions on shell events, such as variable changes or process exits. This allows developers to automate certain tasks in response to specific events.

7. Extensive Customizability

Fish allows developers to customize the prompt, color scheme, and even the shell’s behavior, thanks to its powerful and straightforward scripting capabilities.

In conclusion, Fish shell offers a modern, intelligent, and user-friendly alternative to traditional shells. Its rich features, coupled with a focus on usability and consistency, make it a game-changing tool for developers. Whether you’re a seasoned developer looking for a more productive shell or a novice seeking a friendly introduction to the command line, Fish shell is worth considering.

Give it a try, and you might find your command-line experience transformed.

Understanding Origin and Branches in GitHub

Yoonsoo Park — Sat, 24 Jun 2023 01:25:00 -0400

Introduction

When first delving into the world of version control systems, specifically Git and GitHub, two terms you are likely to encounter often are “origin” and “branch”. However, their usage and what they represent can often lead to confusion. In this article, we will clear up these ambiguities and give you a clear understanding of what “origin” and “branch” are in GitHub.

Origin: The Remote Repository

In Git and by extension, GitHub, “origin” is not a branch as some might mistakenly think. Instead, it is the conventional name given to the default remote repository. Here’s a little context for clarity.

Git is a distributed version control system, which means you work with a local copy of the entire project on your computer. “Origin” is a reference to the remote repository from which the project was originally cloned or copied.

When you clone a repository from GitHub, Git automatically names this remote repository “origin”. Hence, when you run commands like git push origin master, you are instructing Git to push your changes to the “master” branch on the “origin” remote repository.

Branch: Your Development Line

While “origin” refers to the remote repository, a “branch” is an entirely different concept. A branch represents a separate line of development within your project.

The “master” branch (or “main” branch as many repositories are now naming it) is the default branch. It typically represents the stable, production-ready state of your code. Other branches are used for the development of new features, fixing bugs, or experimenting without affecting the stable code.

Once the work on these branches is completed and tested, they can be merged back into the master (or main) branch.

Key Differences

To sum up:

Origin: The default remote repository where your code resides. It’s the original location from which your project was cloned.
Branch: An independent line of development within your project. The master/main branch being the default and typically production-ready branch.

Wrapping up!

Understanding the difference between “origin” and “branch” can go a long way in improving your efficiency with Git and GitHub. Remember that “origin” refers to your remote repository, while a “branch” is your line of development within the project.

Git Vs GitHub

Yoonsoo Park — Fri, 23 Jun 2023 01:25:00 -0400

Introduction

The terms “Git” and “GitHub” are often mentioned together, and for those new to programming or version control systems, this can sometimes lead to confusion. In essence, Git is a version control system, and GitHub is an online service that hosts Git repositories and enhances collaborative work. Let’s delve deeper into their individual roles and the differences between them.

Understanding-Git

Git is a distributed version control system (VCS) that was created by Linus Torvalds, who is also credited with creating Linux. The primary purpose of any VCS is to manage changes to computer programs, documents, large websites, or any other information collections. Git is designed to handle everything from small to extensive projects with speed and efficiency.

Multiple developers can work on the same codebase using Git, without causing conflicts. This is made possible by Git’s ability to create separate environments, known as “branches”. These branches allow developers to work on features or bug fixes independently, and then merge their changes back into the main codebase when they’re ready.

What-is-GitHub?

GitHub, in contrast, is a web-based service that hosts Git repositories. Along with the version control functionality provided by Git, GitHub adds extra features like bug tracking, task management, and project wikis. Essentially, GitHub facilitates team collaboration on projects.

Multiple people can work on code simultaneously, propose changes, review code, discuss issues, and contribute to a codebase in a structured, version-controlled environment on GitHub. GitHub also simplifies “forking” projects (creating a copy of someone else’s project to your account), making changes to that project, and then proposing your changes back to the original project via a “pull request”.

Furthermore, GitHub has a social aspect to it, where users can follow each other, rate each other’s contributions, showcase their own projects, and more.

The-Differences-Between-Git-and-GitHub

To sum it all up:

Git: A version control tool that tracks changes and allows for seamless collaboration in code development.
GitHub: An online service that hosts Git-managed repositories, providing a platform for team collaboration. It also adds its own features for project management and community interaction.

Conclusion

In essence, Git and GitHub complement each other: Git as a powerful tool for version control and GitHub as a platform to collaborate and manage Git repositories. While they are often used together, they perform different roles, each significant in its own right.

Install and Update Salesforce CLI Safely

Yoonsoo Park — Thu, 22 Jun 2023 01:25:00 -0400

This guide was verified against Salesforce’s current CLI documentation on 2026-08-01.

Why the old workflow changed

The standalone sfdx CLI has been unsupported since April 2023. The supported executable is sf, distributed through Salesforce installers and the @salesforce/cli npm package. An old troubleshooting habit was to uninstall packages, delete every .sfdx directory, and reinstall. That mixes three different concerns—program files, configuration, and authorization—and can destroy working credentials without fixing the binary selected by PATH.

Start with the installation owner

Before changing anything, identify every executable and its version:

1
2
3
4


type -a sf
command -v sf
sf version --verbose
npm list --global --depth=0 @salesforce/cli

On macOS, type -a is especially useful because a native installer, Homebrew-managed path, and an npm global installed under a Node version manager can coexist. Update with the same channel that owns the active executable. A Salesforce installer build can self-update with sf update; an npm installation is updated through npm:

1
2
3


npm install --global @salesforce/cli@latest
sf version --verbose
sf doctor

Do not run both approaches merely to be safe. Multiple owners make later debugging harder.

Preserve configuration and authentication

CLI state is not disposable program code. Before a repair, list the org aliases you rely on and confirm that your team has a documented way to reauthenticate. Never copy authorization files into a repository or ticket. Do not use sudo rm -rf against CLI state directories. If a support procedure calls for clearing a specific cache, back it up and limit the change to that diagnosed cache.

For CI, pin an intentional CLI version in the build image or lockfile and update it through a reviewed dependency change. Do not let every pipeline pull latest without validation. Authentication material belongs in the CI secret store, and the build log must not print auth URLs or tokens.

Alternatives and tradeoffs

The native installer is a simple default for a developer workstation and avoids coupling the CLI to an nvm Node version.
npm is useful when a team already controls Node and global-tool versions, but each Node installation can have a different global package directory.
A pinned container gives CI reproducibility, at the cost of maintaining and scanning the image.

Migration checklist

Record type -a sf, sf version --verbose, and the owning package manager.
Remove legacy sfdx-cli only through the package manager that installed it.
Install or update one supported sf distribution.
Open a fresh shell and confirm that the intended binary appears first.
Run sf doctor, then sf org list auth without sharing its sensitive output.
Execute one read-only command against a nonproduction org.
Update scripts from sfdx force:* to their current sf equivalents separately; a binary update does not make old documentation correct.

Official sources

Choose the Right Salesforce Configuration Tool

Yoonsoo Park — Wed, 21 Jun 2023 01:25:00 -0400

Verified on 2026-08-01. “Record-based configuration” is not one Salesforce feature, and Workflow Rules are a legacy automation path.

Choose by responsibility:

Record types select business processes, picklist values, and experiences for materially different processes.
Page layouts and Dynamic Forms control presentation; they are not authorization.
Custom metadata stores deployable application configuration.
Flow is the strategic declarative automation tool; Apex remains appropriate for logic that needs code-level control, testing, or scale.
Permission sets control access.

Avoid a record type for every minor variation. Start with the business process and security boundary, then select the smallest mechanism. The tradeoff is governance: declarative tools are approachable but still need source control, tests, owners, and limits.

Migration: inventory Workflow Rules and overloaded record types, add regression tests, migrate automation through Salesforce’s supported Flow tooling, activate in a controlled release, and monitor failed Flow interviews.

References: Migrate to Flow, Custom Metadata Types.

Start with the decision, not the feature

Write down what varies, who may change it, whether it moves between orgs, and whether it affects UI, access, or automation. A record type is appropriate only when one object supports materially different processes. It should not become a generic flag for every conditional.

Step-by-step example

Suppose Projects have Internal and Client delivery processes. Use record types only if picklist values or process stages truly differ. Use Dynamic Forms for conditional field visibility, permission sets for access, custom metadata for deployable thresholds, and a record-triggered Flow for automation. Then:

Define developer names and ownership in source control.
Build permission sets before page visibility rules so hidden UI is never mistaken for security.
Put environment-independent policy in custom metadata, not hard-coded record IDs.
Bulk-test the Flow, including update recursion and failure paths.
Deploy to a sandbox, assign to a pilot permission-set group, and inspect failed interviews.

Alternatives and tradeoffs

One record type plus Dynamic Forms reduces administrative branching but cannot represent different sales/support business processes by itself. Custom settings can hold runtime configuration, while custom metadata is generally better for deployable configuration. Apex provides transaction control and reusable abstractions but requires code ownership. Flow is accessible and observable, yet large monolithic flows become as difficult to maintain as monolithic code.

Migration checklist

Inventory record types, layouts, Workflow Rules, Process Builder processes, validation rules, permissions, and hard-coded IDs together. Map each behavior to an owner and test. Use the supported migration tooling as a starting point, not proof of equivalence. Disable old automation only after side-by-side tests show that ordering, recursion, scheduled paths, and error handling match. Keep rollback artifacts until production monitoring is clean.

Verification

Test each persona, record type, create/update/bulk transaction, and denied field. Confirm metadata deploys without org-specific IDs. Monitor Flow errors and business outcomes after release. The best configuration is the smallest set of mechanisms whose responsibilities a future maintainer can explain.

Retreive GitHub Pull Requests Code

Yoonsoo Park — Tue, 20 Jun 2023 01:25:00 -0400

When collaborating on a shared repository, it’s typical to review pull requests (PRs) made by other contributors. While it’s possible to view these PRs through the GitHub web interface, there’s an often-overlooked alternative that provides a more thorough review process - reviewing them directly from your local machine via the command line.

The Advantages of Local Review

By fetching and checking out pull requests locally, you’re not just reviewing the code - you’re running it on your machine. This ability to execute the code offers a more practical and precise code review. It allows you to explore how the changes interact with the existing codebase, test the code in various scenarios, and identify potential bugs or issues that may not be immediately apparent when reviewing the code on the web interface.

Additionally, developers often find it more comfortable and efficient to read and understand code within their local development environment, as they can leverage familiar tools and configurations.

Without further ado, let’s delve into the steps needed to review GitHub PRs locally.

Step 1: Fetch the PR

Firstly, you need to fetch the PR from the remote repository using this git command:

1

git fetch origin pull/PR_NUMBER/head:pr-PR_NUMBER

Remember to replace PR_NUMBER with the actual number of the PR. For example, if you’re fetching pull request #123, the command would be:

1

git fetch origin pull/123/head:pr-123

Step 2: Checkout the PR

Having fetched the PR, it’s now time to check it out into a new branch with the following command:

1

git checkout pr-PR_NUMBER

Again, replace PR_NUMBER with the actual number of the PR. So, if the PR number was 123, you’d use:

1

git checkout pr-123

This command switches your working directory to the new branch (pr-123 in our example), giving you access to the proposed changes.

Step 3: Review and Run the PR

With the PR branch checked out, you can now proceed with the code review. But now, you have the advantage of being able to actually run the code. This allows you to identify potential runtime errors, understand how the new changes behave under different scenarios, and check the compatibility with your existing codebase.

After a thorough assessment, you’re now ready to provide constructive feedback, propose changes, or approve the pull request.

Conclusion

Although the GitHub web interface is a convenient tool for reviewing PRs, checking them out locally allows for a more comprehensive review process. By fetching and running the changes proposed in a pull request on your machine, you can deliver higher quality feedback and help ensure the stability and efficiency of your shared codebase. After your review, remember to switch back to your original branch and clean up the PR branches to keep your local repo organized.

Safely Remove Unwanted Files from a Pull Request

Yoonsoo Park — Mon, 19 Jun 2023 01:25:00 -0400

Removing a file from a pull request is not one Git operation. The safe command depends on whether the file is untracked, staged, committed, pushed, or intentionally deleted. Treating these states as interchangeable is how unrelated work gets lost.

This guide was verified on 2026-08-01 against the official documentation for git status, git restore, and GitHub pull requests. Run git status --short before and after every correction.

Start with the pull request’s actual difference

Fetch the target branch and inspect the merge-base comparison used by a pull request:

1
2
3
4


git fetch origin
git status --short
git diff --name-status origin/main...HEAD
git diff origin/main...HEAD -- path/to/file

Replace origin/main with the PR’s real base branch. Three dots compare the merge base with the proposed branch tip; two dots compare two endpoint trees and can include unrelated base-branch movement.

If GitHub CLI is available, gh pr diff --name-only is another useful view. Neither command changes files.

Case 1: the file is only staged

Keep the working copy but remove it from the next commit:

1
2


git restore --staged -- path/to/file
git status --short

If the file should never be committed, add an appropriate shared pattern to .gitignore, or use .git/info/exclude for a personal local-only pattern. Ignore rules do not stop tracking a file that is already committed.

Case 2: discard an uncommitted edit to a tracked file

Preview it, then restore only that path:

1
2


git diff -- path/to/file
git restore --source=HEAD --worktree -- path/to/file

This intentionally discards the path’s unstaged change. Copy or stash the file first if any part is worth keeping. Avoid repository-wide git restore ., git checkout -- ., or git reset --hard: their scope is much larger than the stated task.

Case 3: the unwanted change is already committed

Restore that file from the PR base, then commit the correction:

1
2
3
4
5


git fetch origin
git restore --source=origin/main --staged --worktree -- path/to/file
git diff --cached -- path/to/file
git commit -m "Restore path excluded from this pull request"
git push

This preserves published history and makes the correction reviewable. It works whether the PR accidentally modified or deleted the tracked file. If the branch deliberately needs a clean, rebased history, interactive rebase is an alternative, but rewriting pushed commits requires coordination and normally a guarded --force-with-lease. It is not the default cleanup method.

Case 4: remove a file from the project

If the PR is supposed to delete the file, use git rm and review the staged deletion:

1
2
3


git rm -- path/to/file
git diff --cached -- path/to/file
git commit -m "Remove obsolete file"

To stop tracking a generated or local file while keeping the working copy, first add the correct ignore rule and then use:

1
2


git rm --cached -- path/to/file
git diff --cached -- path/to/file

This is a repository decision because collaborators will also stop receiving that path.

Forks, generated files, and secrets

For a PR from a fork, push the correction to the same head branch. Creating another branch does not update the existing PR automatically.

Generated lockfiles, snapshots, and migrations should not be removed merely because they are large. Confirm the repository policy and reproduce the generator instead of hand-editing output.

If the file contains a credential, removing it in a later commit does not remove it from Git history. Revoke or rotate the secret immediately, notify the repository owner, and follow GitHub’s sensitive-data removal guidance. History rewriting is a coordinated incident-response action.

Verification checklist

1
2
3


git status --short
git diff --name-status origin/main...HEAD
git diff origin/main...HEAD -- path/to/file

The final PR diff should contain only intended changes. Run the project’s tests, check generated artifacts according to repository policy, and read the web PR once more before requesting review.

When several files are involved, repeat the path-scoped procedure instead of widening the command to the repository root. A sequence of small, named correction commits is easier to review and can be squashed later if the repository prefers a compact history. The important property is observability: before each write, know which Git state will change; after each write, confirm it with status and the PR diff. That discipline is more reliable than memorizing one cleanup command.

How to Add Tags in GitHub

Yoonsoo Park — Sun, 18 Jun 2023 01:25:00 -0400

Tags in GitHub are a great way to mark specific points in your project’s history, such as significant releases or milestones. They provide a reference point for easier navigation and can be useful for collaboration and version control. In this article, we’ll explore two methods of adding tags in GitHub: using Git commands and using the web user interface (UI).

Adding Tags Using Git Command

Step 1: Clone the Repository: Begin by cloning the repository to your local machine using the following command:

git clone <repository-url>

Step 2: Navigate to the Repository: Move into the repository’s directory using the cd command:

cd <repository-directory>

Step 3: Check Out the Desired Commit: Use the git log command to view the commit history. Find the commit you want to tag and note its commit hash. Then, check out the commit using the following command:

git checkout <commit-hash>

Step 4: Create the Tag: Now, create the tag using the git tag command. You can choose either an annotated or lightweight tag. For an annotated tag, use the following command:

git tag -a <tag-name> -m "<tag-message>"

For a lightweight tag, use:

git tag <tag-name>

Step 5: Push the Tag to GitHub: Finally, push the tag to the remote repository on GitHub with the git push command:

git push origin <tag-name>

Adding Tags Using Web UI

Step 1: Navigate to the Repository: Open your web browser and go to GitHub. Navigate to the repository where you want to add the tag.
Step 2: Go to the Releases Section: Once you’re in the repository, click on the “Releases” tab located near the top navigation bar.
Step 3: Create a New Release: On the releases page, click on the “Create a new release” button.
Step 4: Fill in Release Details: In the release creation form, enter the tag version, release title, and any other relevant information.
Step 5: Publish the Release: After filling in the necessary details, click on the “Publish release” button to create the tag and publish the release.

NOICE! You have successfully added a tag to your GitHub repository. Whether you prefer using Git commands or the web UI, both methods provide an efficient way to mark important points in your project’s history.

Remember, tags are useful for organizing and tracking different versions of your project. They can also be used to trigger specific actions, such as deployment or CI/CD pipelines. Utilize tags wisely to enhance collaboration and streamline your development workflow.

Note: If you’re using a different Git platform or hosting service, the steps may vary slightly. However, the general concept of adding tags remains the same.

My first article from my first house! ;)

Best Practices for Defining Paths for RESTful APIs

Yoonsoo Park — Sat, 17 Jun 2023 01:25:00 -0400

Best Practices for Defining Paths for RESTful APIs

When creating RESTful APIs, it’s important to adhere to the best practices for defining paths. Below are a few guidelines:

Use nouns, not verbs: RESTful APIs should use nouns (not verbs) to indicate the resources being manipulated. The HTTP methods (GET, POST, PUT, DELETE, etc.) should define the operation. For example, use /users/{userId} instead of /getUser/{userId}.
Pluralize resources: It’s generally recommended to use plural forms of resources to indicate a collection. For instance, /users represents all users, while /users/{userId} represents a specific user.
Avoid deep nesting: While it may be tempting to deeply nest resources, this can lead to complex and less manageable APIs. Instead, limit your API paths to two levels if possible. For example, use /users/{userId}/posts rather than /users/{userId}/posts/{postId}/comments.
Lowercase letters and hyphens: Use lowercase letters in the path. If you need to separate two words, use hyphens (-) instead of underscores (_) or camel case.
Consistency: Above all, be consistent in your naming and structuring conventions. Consistency helps to maintain clarity for all developers who are using your API.
Use Meaningful Resource Names

Ensure that resource names are intuitive and meaningful. They should clearly indicate what kind of data is being represented by the API. For example, /employees is a more intuitive resource name than /people when you’re dealing with an API for a human resources application.

Avoid Query Parameters for Mandatory Data

While query parameters can provide flexibility, they should not be used for mandatory data. Mandatory data should be provided as path parameters instead. For instance, use /users/{userId} instead of /users?userId={userId}.

Versioning Your APIs

It’s recommended to include a version in your API path to prevent breaking changes for your API consumers. For instance, /v1/users/{userId}. This allows you to evolve your API without interrupting service for existing clients.

Real-Life Examples

Let’s look at a real-life example - an API for a blog application. Here are some endpoints that follow the best practices:

GET /v1/posts - Retrieves all blog posts.
GET /v1/posts/{postId} - Retrieves a specific blog post.
POST /v1/posts - Creates a new blog post.
PUT /v1/posts/{postId} - Updates a specific blog post.
DELETE /v1/posts/{postId} - Deletes a specific blog post.
GET /v1/users/{userId}/posts - Retrieves all posts from a specific user.

Note that we have a version number in the paths, we’re using plural and meaningful resource names (posts), and we’re not using query parameters for mandatory data (postId and userId are path parameters).

Adhering to these best practices when defining paths will help to create APIs that are not only powerful and scalable, but also user-friendly and easy to maintain. Consistency, intuitive resource names, correct use of path and query parameters, and proper versioning are all essential for a well-structured API.

Path Parameters in Amazon API Gateway

Yoonsoo Park — Fri, 16 Jun 2023 01:25:00 -0400

Path parameters identify a resource inside a route: GET /users/{userId}. API Gateway matches the route and passes the captured value to the integration. The braces belong to the API Gateway route definition; a backend framework may use different syntax, such as Express /users/:userId.

HTTP API and REST API events

For a Lambda proxy integration, read the decoded route values from pathParameters rather than parsing the raw path yourself.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


import type { APIGatewayProxyHandlerV2 } from "aws-lambda";

export const handler: APIGatewayProxyHandlerV2 = async (event) => {
 const userId = event.pathParameters?.userId;
 if (!userId || !/^[a-zA-Z0-9_-]{1,64}$/.test(userId)) {
 return { statusCode: 400, body: JSON.stringify({ error: "invalid userId" }) };
 }

 // Authorization must confirm the caller may read this user.
 return { statusCode: 200, body: JSON.stringify({ userId }) };
};

Payload shapes differ between HTTP API payload versions and REST API proxy events. Type and test against the integration actually deployed. A greedy route such as /{proxy+} captures multiple path segments; use it when the backend intentionally owns routing, not as a shortcut that hides the API contract.

Resource modeling

Use a path value for the identity or hierarchy of the addressed resource, for example /orders/{orderId}. Use query parameters for filtering, sorting, pagination, and optional views, for example /orders?status=open&cursor=.... “Required” does not automatically mean “path”: a required search filter can still be a query parameter, while a resource identifier naturally belongs in the path.

Nested paths such as /users/{userId}/posts/{postId} are useful when the relationship is part of the authorization or identity. Avoid deep nesting when the child has a stable independent identifier. Consistency and a documented OpenAPI contract matter more than a universal pluralization or depth rule.

Validation and security

A syntactically valid path parameter is not authorization. Prevent insecure direct object references by checking the caller’s access to the resolved resource. Validate length and character set, handle percent-encoding consistently, and do not concatenate an unchecked value into SQL, filesystem paths, log formats, or downstream URLs.

Return consistent error semantics: usually 400 for malformed input, 401/403 for authentication or authorization failure, and 404 when the resource is absent according to the API’s disclosure policy. Configure route-level throttling and observe latency and errors by route without putting sensitive IDs into high-cardinality metric dimensions.

Verification checklist

Test missing, empty-equivalent, oversized, Unicode, encoded slash, and invalid-character values.
Confirm HTTP API or REST API event shape and payload version.
Test a valid ID owned by another user.
Verify greedy-route precedence and the deployment stage/base path.
Keep the OpenAPI route, infrastructure definition, and handler tests aligned.

Official documentation reviewed on 2026-08-01:

Use AWS Temporary Credentials Without Reading Cache Files

Yoonsoo Park — Thu, 15 Jun 2023 01:25:00 -0400

Temporary credentials contain an access key ID, secret access key, and usually a session token. Applications need them to sign AWS requests, but applications usually should not retrieve, store, or refresh those values directly. They should ask a credential provider when the SDK needs to sign a request.

This distinction matters. Reading the first file under ~/.aws/sso/cache, extracting its access token, and running aws sso get-role-credentials assumes an internal cache layout, may select another login, and can expose a bearer token through shell arguments. It also turns application code into a partial credential manager.

One application, different providers

Use the SDK for JavaScript v3 default provider chain:

1
2
3
4
5


import { S3Client, ListBucketsCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({ region: process.env.AWS_REGION ?? "us-east-1" });
const result = await s3.send(new ListBucketsCommand({}));
console.log(result.Buckets?.map((bucket) => bucket.Name));

There is deliberately no credential object. In local Node.js development, the provider can resolve AWS_PROFILE from shared config, including IAM Identity Center. In ECS or EC2 it can resolve the attached role. In EKS or external CI it can resolve web identity. This keeps environment-specific authentication outside business code and allows refresh.

Local operator flow:

1
2
3
4


aws configure sso --profile engineering-dev
aws sso login --profile engineering-dev
AWS_PROFILE=engineering-dev aws sts get-caller-identity
AWS_PROFILE=engineering-dev node dist/list-buckets.js

Deployed workload flow: attach a least-privilege workload role and run the same program without AWS_PROFILE. Never copy a local SSO cache into a container image.

When to choose an explicit provider

Use fromIni({ profile }) when a local tool intentionally accepts a named profile or assumes a role from it. Use fromTemporaryCredentials for an explicit role-assumption chain. Use fromTokenFile for web identity environments. These providers return functions so the SDK can refresh values. Avoid resolving once and spreading the raw keys into many clients.

Do not let an untrusted request choose an arbitrary local profile or role ARN. Treat identity selection as configuration with an allowlist. Verify account and ARN at startup for tools that can mutate infrastructure.

Failure and observability

Differentiate “no credential source”, “interactive session expired”, “role trust denied”, and “service action denied”. The remedy for an expired workforce session is an explicit login—not scanning other cache files. Record the selected profile name, Region, account, role ARN, request ID, and error code where appropriate; never record secrets or tokens.

Alternatives and migration

AWS CLI commands already use the shared provider behavior, so a shell-only workflow may not need SDK code. A legacy program that only accepts environment variables may use the CLI-supported export-credentials command for a bounded child process. Static IAM access keys should remain a last resort for unsupported workloads.

Migration checklist:

Remove filesystem reads of SSO cache and access-token parsing.
Remove shell calls to sso get-role-credentials.
Use modular SDK clients and the default provider, or one documented explicit provider.
Separate workforce, CI, and deployed workload authentication.
Verify the expected account and least-privilege action set.
Test expiration and automatic refresh during a long-running process.
Delete copied credential files and revoke any accidentally exposed session.

Make the provider boundary visible in design

A useful application interface accepts an SDK client or a provider function, not three credential strings. That keeps authentication in the composition root and lets tests inject a client with a mock transport. It also avoids a common refresh bug: one module obtains temporary credentials, serializes them into configuration, and other modules continue using them after expiry.

For role assumption, set a meaningful role session name and use source identity or session tags only when the trust and authorization design needs them. Keep role chains short because each hop adds policy reasoning and session-duration constraints. External IDs are for confused-deputy protection in third-party cross-account access; they are not secrets and do not replace a narrow trust principal.

Operationally, alert on access denied patterns and unexpected role assumption, not on the presence of an access key ID. CloudTrail records the assumed-role session and is the place to connect activity to the workload. Use IAM Access Analyzer to validate policies and reduce permissions after observing the actions required by the application.

Before removing a legacy credential path, run a canary with the provider-based build, force a credential refresh, and verify representative calls. Disable an old IAM key before deletion and watch for failed dependencies during a bounded rollback window. This separates a recoverable migration from indefinite dual authentication.

Verified on 2026-08-01.

Official sources

The Art of Decision-Making - Why Engineers Should Stop Being Imposters

Yoonsoo Park — Wed, 14 Jun 2023 01:25:00 -0400

Don’t just be an engineer, be an imposter! Wait, what? That’s right, folks. In the world of software development, it seems like many engineers have taken on the role of the indecisive imposter, desperately seeking approval for even the tiniest of decisions. But hey, who needs efficiency and progress when we can waste company resources and time, am I right?

Analysis Paralysis: The Rabbit Hole of Never-Ending Decisions

Let’s set the stage. You’re an engineer working on a complex software project. You’re faced with a decision, whether it’s choosing the right library, deciding on an architectural approach, or simply picking the color of a button. But instead of taking charge and making a call, you find yourself stuck in the abyss of analysis paralysis.

Analysis paralysis, a term coined for this very situation, refers to the state of overthinking and overanalyzing to the point where a decision becomes nearly impossible. It’s like being trapped in a never-ending loop of “What if?” and “But what about this?”

The Need for Decisiveness: Taking Responsibility

As engineers, we must embrace the critical mindset of decision-making. We need to acknowledge that our ability to make informed choices is what drives progress and success. It’s not about seeking approval or waiting for someone else to make the call. No, it’s about taking responsibility for our decisions and standing by them.

Thomas Edison, the inventor of the light bulb, once said, “I have not failed. I’ve just found 10,000 ways that won’t work.” Edison understood that making decisions, even if they turn out to be wrong, is a crucial part of the journey to success. So why are we so afraid to make decisions?

Unnecessary Meetings: The Signature Move of an Imposter

Picture this: you’re in a meeting room filled with your fellow engineers, managers, and stakeholders. The topic of discussion? The color of a button. Yes, you heard that right—a button. The room is buzzing with opinions, ideas, and a whole lot of wasted time. And why? Because you, the indecisive engineer, wanted approval from the authority figures.

Albert Einstein, the brilliant physicist, once remarked, “The measure of intelligence is the ability to change.” Yet, in this scenario, it seems like intelligence has taken a backseat. By seeking approval for the minutest of decisions, engineers inadvertently become imposters, wasting valuable company resources.

The Imposter Syndrome: A Good Sign?

Being an imposter in the software development field might not be what you think. It’s not about pretending to know things you don’t. No, it’s about shying away from the responsibility of making decisions and hiding behind the need for approval. The imposter engineer thrives on unnecessary meetings and the collective decision-making process, all while draining the company’s resources.

So, the next time you find yourself hesitating to make a decision, take a moment to reflect. Are you falling into the imposter syndrome trap? Are you wasting time, money, and the potential of your team? Remember the wise words of Mark Twain: “Twenty years from now, you will be more disappointed by the things you didn’t do than by the ones you did.”

Embrace the Decisive Engineer Within

In a world that demands progress and innovation, engineers cannot afford to be imposters. It’s time to break free from the analysis paralysis rabbit hole and take responsibility for our decisions. Let’s embrace the critical mindset that defines our profession and make the choices that propel us forward.

As engineers, we have the power to shape the future. So, let’s make decisions, take risks, and learn from our mistakes. After all, as the legendary Steve Jobs once said, “The people who are crazy enough to think they can change the world are the ones who do.”

Remember, the imposter syndrome might be a good plot twist for a game, but in the real world of software development, it’s time to leave that role behind. Be decisive, be responsible, and be the engineer you were meant to be.

Disclaimer: This article is intended for entertainment purposes. (or is it?)

Cheers! 🍺

Sign API Gateway Requests with SigV4 and AWS SDK for JavaScript v3

Yoonsoo Park — Tue, 13 Jun 2023 01:25:00 -0400

Signature Version 4 proves that an AWS request was signed by credentials authorized to perform an action. For API Gateway, it is useful when callers already have AWS identities: internal workloads, operators using federation, or CI using OIDC. It is not a replacement for end-user authentication in a public browser application.

The older pattern combined the end-of-support AWS SDK for JavaScript v2, a third-party signer, and access keys in source code. The current pattern uses modular v3 packages and the default credential provider chain.

Configure the API and caller

Set the API Gateway route or method authorization type to AWS_IAM. Grant the caller execute-api:Invoke only on the required API, stage, method, and resource path. The API’s resource policy and network policy may impose additional limits.

For local development, log in with IAM Identity Center. On Lambda, ECS, or EC2, attach a role. The same code can use both because it does not contain keys.

1
2


npm install @aws-sdk/signature-v4 @aws-sdk/protocol-http \
 @aws-sdk/credential-provider-node @aws-crypto/sha256-js

Sign and send

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


import { SignatureV4 } from "@aws-sdk/signature-v4";
import { HttpRequest } from "@aws-sdk/protocol-http";
import { defaultProvider } from "@aws-sdk/credential-provider-node";
import { Sha256 } from "@aws-crypto/sha256-js";

const region = "us-east-1";
const url = new URL(
 "https://abc123.execute-api.us-east-1.amazonaws.com/prod/orders"
);
const body = JSON.stringify({ orderId: "123" });

const signer = new SignatureV4({
 service: "execute-api",
 region,
 credentials: defaultProvider(),
 sha256: Sha256,
});

const request = new HttpRequest({
 protocol: url.protocol,
 hostname: url.hostname,
 method: "POST",
 path: `${url.pathname}${url.search}`,
 headers: {
 host: url.hostname,
 "content-type": "application/json",
 },
 body,
});

const signed = await signer.sign(request);
const response = await fetch(url, {
 method: signed.method,
 headers: signed.headers,
 body,
});

if (!response.ok) {
 throw new Error(`API returned ${response.status}: ${await response.text()}`);
}

The exact body, path, query string, host, and signed headers sent over the network must match what was signed. Do not mutate JSON or add a proxy path afterward. Temporary credentials require the session token; the provider supplies it to the signer.

Debugging without exposing secrets

On a 403, distinguish an API authorization failure from SignatureDoesNotMatch. Confirm the account and ARN with STS, Region, service name execute-api, deployed stage/path, clock synchronization, resource ARN, and API resource policy. Log request IDs and non-sensitive canonical inputs, never the Authorization header, session token, or credentials.

Alternatives and tradeoffs

SigV4 gives strong workload identity and IAM policy control, but browsers cannot safely hold AWS credentials. Use Cognito/OIDC JWT authorization or another application identity layer for end users. For service-to-service calls outside AWS identity boundaries, OAuth 2.0 may provide a better contract. API keys in API Gateway identify usage-plan consumers; they are not authorization by themselves.

Migration checklist

Remove SDK v2, aws4, and explicit access keys.
Enable AWS_IAM only for callers that can obtain AWS credentials safely.
Use Identity Center, workload roles, or OIDC and the provider chain.
Scope execute-api:Invoke to the necessary route.
Test GET, query encoding, and non-empty body requests.
Test expired credentials, wrong Region, wrong route, and denied IAM permissions.
Verify CloudTrail/API logs without recording signed secrets.

Canonicalization cases worth testing

SigV4 bugs often hide in inputs that a happy-path GET does not cover. Test repeated query keys, spaces and Unicode, an empty body, a JSON body, and a path containing percent-encoded characters. Build the final serialized body once, sign those bytes, and send those same bytes. If a library or proxy normalizes the path or host after signing, the service calculates a different canonical request.

Credential-provider behavior deserves its own test boundary. In unit tests, inject a fixed fake provider into the signer; never depend on a developer profile. In an integration environment, assume a dedicated low-privilege role, invoke an allowed route, and confirm a neighboring method and route are denied. This proves both the positive path and the resource ARN scope.

For cross-account invocation, the API owner may need a resource policy in addition to the caller’s identity policy. For private APIs, endpoint and VPC policies add more policy layers. Diagnose each layer independently rather than broadening all of them until the call succeeds. A temporary execute-api:* grant can conceal an incorrect route ARN and is easy to leave behind.

Finally, retry only operations that are safe to retry. Signature or authorization errors will not recover with exponential backoff. For mutating APIs, use an application idempotency key so a network retry cannot create a duplicate business action.

Verified on 2026-08-01.

Official sources

Designing Reliable Work Queues with Amazon SQS

Yoonsoo Park — Mon, 12 Jun 2023 01:25:00 -0400

Amazon SQS decouples producers from consumers, absorbs bursts, and retains work during temporary consumer failures. Reliability still depends on the consumer design. SQS does not by itself guarantee that a business operation happens exactly once.

Choose Standard or FIFO

Standard queues provide very high throughput, at-least-once delivery, and best-effort ordering. A message can be delivered more than once, so consumers must be idempotent.

FIFO queues preserve order within a message group and provide SQS deduplication semantics. They are useful when order is a real invariant, but message-group design affects concurrency. FIFO does not make an external database charge or API call exactly once; the consumer still needs an idempotency key or transactional boundary.

The processing contract

Receiving a message makes it temporarily invisible. Delete it only after the business operation commits. Set the visibility timeout longer than normal processing plus a margin, and extend it with ChangeMessageVisibility for legitimately long work. If it is too short, another worker can process the same message concurrently; if too long, recovery from a crashed worker is delayed.

Use an immutable message ID or business idempotency key. Store the result atomically where possible, or make the target API accept the key. Retries must use backoff and distinguish transient errors from permanent invalid input.

Configure a dead-letter queue with a deliberate maxReceiveCount. A DLQ is not a trash can: alarm on it, preserve enough context to diagnose safely, and define a reviewed redrive procedure. Redriving without fixing the cause can repeat side effects or create another outage.

Efficient consumers

Use long polling to reduce empty receives and batch receive/delete operations where failure handling remains correct. Scale consumers on queue depth and age of oldest message, not CPU alone. Cap concurrency to protect databases and downstream APIs. For Lambda event source mappings, understand partial batch responses so one failed record does not force successful records through unnecessary retries.

Encrypt queues when required, use TLS, and scope producer/consumer IAM permissions to specific queues and actions. Avoid sensitive payloads when a reference to encrypted storage is sufficient. Remember retention and DLQ retention in privacy and deletion policies.

Order example

Do not represent an entire order workflow as unrelated messages that can independently charge, reserve inventory, and notify without coordination. Publish a durable order identifier, make each step idempotent, record state transitions, and use a workflow or saga when compensation and ordering matter. SQS transports work; it is not the system of record.

Verification checklist

Deliver the same message twice and confirm one business effect.
Kill a worker after commit but before delete.
Run longer than the visibility timeout and test extension.
Trigger transient retries and poison-message DLQ routing.
Test partial batch failure and redrive.
Alarm on age, visible/not-visible count, DLQ depth, consumer errors, and throttling.
Load test with downstream concurrency limits in place.

Official documentation reviewed on 2026-08-01:

Secure Direct Uploads with Amazon S3 Presigned URLs

Yoonsoo Park — Sun, 11 Jun 2023 01:25:00 -0400

An S3 presigned URL lets a client perform one signed S3 operation without receiving AWS credentials. Direct upload avoids sending large files through the application server, but a presigned URL is not automatically safe: anyone who obtains it can use it until it expires or the signing credentials stop being valid.

A safer upload flow

The authenticated client asks the application for permission to upload metadata such as file name, size, and media type.
The application authorizes the user and generates an unpredictable object key inside that user’s allowed prefix.
The application returns a short-lived presigned PUT URL or presigned POST policy.
The client uploads directly to S3.
An S3 event or explicit completion request starts validation, malware scanning, metadata extraction, and publication. Keep untrusted uploads in a quarantine prefix or bucket until this finishes.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


import boto3

s3 = boto3.client("s3")
url = s3.generate_presigned_url(
 "put_object",
 Params={
 "Bucket": "private-upload-bucket",
 "Key": "incoming/user-123/7a4f...",
 "ContentType": "image/png",
 },
 ExpiresIn=300,
)

The client must send the same signed content type. For stricter size constraints, use a presigned POST policy with content-length-range, or enforce limits through another trusted boundary. For large uploads, use multipart upload and abort incomplete uploads with an S3 lifecycle rule.

Security boundaries

Use the shortest practical expiration. A URL signed with temporary credentials cannot outlive those credentials.
Treat the URL as a bearer secret: do not put it in analytics, chat, referer-bearing pages, or durable logs.
Give the signing role access only to the required bucket, operation, and key prefix.
Keep Block Public Access enabled; a presigned URL does not require public objects.
Consider checksums, allowed content type, unique keys, server-side encryption, retention, and overwrite behavior.
Configure CORS only for trusted origins and necessary methods/headers. CORS is a browser control, not authorization.
Do not make an upload public until server-side validation succeeds.

Revocation is limited. Removing the object does not invalidate an upload URL, and a generated URL has no independent revoke button. You can revoke or restrict the credentials/policy used to sign it, but that affects other requests. Short expiry and narrowly scoped signing permissions are the practical controls.

When server-side upload is better

Proxy through the application when it must inspect or transform every byte before storage, the client cannot talk to S3, or centralized rate limiting outweighs bandwidth cost. Presigned direct upload is preferable for large trusted workflows, but it moves validation to an asynchronous boundary that must be designed explicitly.

Migration verification: confirm private bucket policy, signing-role scope, expiry, wrong-user denial, size/type rejection, duplicate key behavior, incomplete multipart cleanup, scanner failure, and secret-free logging.

Official documentation reviewed on 2026-08-01:

Choosing When to Use Amazon API Gateway

Yoonsoo Park — Sat, 10 Jun 2023 01:25:00 -0400

Amazon API Gateway is a managed front door for HTTP, REST, and WebSocket APIs. It can provide routing, authorization, throttling, metrics, stages, and integrations without requiring a team to operate an API proxy fleet. That does not mean every service needs it.

Start with the requirement

Choose API Gateway HTTP API for a relatively simple Lambda or HTTP proxy API when JWT/OIDC authorization, IAM authorization, custom domains, CORS, and lower cost are important. Choose API Gateway REST API when a required feature is available only there, such as usage plans/API keys, request validation or transformation capabilities, or particular caching and private API patterns. Check the official feature comparison because the two products are not interchangeable.

Consider alternatives:

Lambda Function URL: one Lambda, simple ingress, and no need for API Gateway’s broader management features.
Application Load Balancer: existing container or instance services, long-lived connections, or load-balancer-native routing.
AWS AppSync: GraphQL and managed real-time/data-source integration requirements.
Direct service-to-service integration: asynchronous EventBridge, SNS, or SQS may be a better boundary than a synchronous API.

Security is configuration, not a default outcome

Pick authorization for the caller: IAM/SigV4 for AWS workloads, JWT authorizers for OIDC identities, Cognito user pools where appropriate, or a Lambda authorizer for genuinely custom logic. An API key identifies a usage-plan consumer; it is not authentication by itself.

Apply throttling and quotas intentionally, validate input at the application boundary, restrict backend roles, and avoid logging tokens or sensitive request bodies. A private API or resource policy can reduce network exposure, but authorization remains necessary.

Operations and cost

API Gateway scales the managed entry point, not the backend. Set Lambda concurrency, database connection limits, retries, and timeouts so a traffic spike does not move the failure downstream. Emit access logs with request IDs, metrics and alarms for latency, 4xx/5xx responses, integration errors, and throttles. Sample tracing where it answers an operational question.

Pricing differs by API type, Region, request volume, payload and data transfer. Compare the live pricing page with ALB or direct alternatives for the expected traffic shape rather than assuming pay-per-request is always cheaper.

A small decision checklist

Identify protocol, caller identity, traffic shape, payload size, and latency target.
List the required authorization, transformation, caching, WebSocket, and private-network features.
Pick HTTP API by default when it meets the list; use REST API only for a required REST-specific capability.
Test throttling, authorization denial, backend timeout, malformed input, and deployment rollback.
Verify logs and alarms without collecting secrets.

Official documentation reviewed on 2026-08-01:

Getting to Yes - Negotiating Agreement Without Giving In by Roger Fisher

Yoonsoo Park — Fri, 09 Jun 2023 01:25:00 -0400

A Key Resource for Persuasive Negotiation in Software Engineering

“Getting to Yes: Negotiating Agreement Without Giving In” by Roger Fisher, William Ury, and Bruce Patton is a seminal text that offers a roadmap for negotiating mutually beneficial agreements in any situation. Its principles are particularly beneficial when trying to persuade others in the software engineering world, especially in discussions around project scope, resources, and timelines.

Four Principles of Effective Negotiation

The authors outline four principles for effective negotiation, which should be observed at each stage of the negotiation process, from analyzing the situation, planning responses, to discussing the problem to find a common solution.

Separate the People from the Problem: People often become personally involved with the issues and their side’s positions. The authors stress the importance of separating the people from the issues to avoid damaging relationships and to get a clearer view of the substantive problem【14†source】.
Focus on Interests, Not Positions: Rather than bargaining from separate opening positions, which often leads to inefficient and unfair agreements, Fisher and Ury suggest focusing on the underlying interests of all parties involved.
Generate a Variety of Options Before Settling on an Agreement: Instead of rushing to find a single answer, the authors advise generating multiple options to solve the problem. This allows for a more comprehensive exploration of possible solutions that could satisfy all parties.
Insist That the Agreement Be Based on Objective Criteria: To ensure fairness and durability, the agreement should be grounded on objective criteria rather than personal bias or power dynamics.

Although I was unable to find explicit real-world examples of these principles in action within the software engineering context due to time constraints and technical issues, they are widely applicable in a range of scenarios. For instance, when negotiating project resources, one might focus on the interests of delivering a quality product on time (a shared interest) rather than sticking to initial positions (e.g., I need X amount of resources). Multiple options for resource allocation could be explored, and the final agreement should be based on objective criteria such as project requirements and available resources.

These principles can serve as a guide for software engineers and project managers, helping to transform negotiations from battles into collaborative problem-solving sessions, fostering better relationships, and leading to more efficient and satisfactory outcomes.

“Never argue with stupid people. They will drag you down to their level and then beat you with experience.” - Mark Twain

Cheers! 🍺

Export IAM Identity Center Credentials Only When a Tool Requires Them

Yoonsoo Park — Thu, 08 Jun 2023 01:25:00 -0400

Most AWS-aware applications should receive a profile name and use the standard credential provider chain. Occasionally, a legacy tool understands only AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_SESSION_TOKEN. That is an interoperability exception, not a reason to parse ~/.aws/sso/cache or call the IAM Identity Center API yourself.

Why the old approach changed

An Identity Center cache can hold several sessions. Selecting the first JSON file may choose the wrong identity, and the cache schema is not a supported integration contract. Passing an access token on a shell command line can also expose it through logs or process inspection. The AWS CLI already knows which cached session belongs to a profile and how to exchange it for role credentials.

Prefer direct profile support

1
2
3


aws configure sso --profile engineering-dev
aws sso login --profile engineering-dev
AWS_PROFILE=engineering-dev aws sts get-caller-identity

If the target tool supports AWS profiles, stop here:

1

AWS_PROFILE=engineering-dev your-tool

For SDK code, omit explicit keys and use the default provider chain. For CI or hosted workloads, use OIDC or a workload role instead of a human Identity Center session.

Supported export for a legacy process

AWS CLI v2 provides aws configure export-credentials. Verify your CLI exposes the command, then export only into the current shell immediately before launching the tool:

1
2
3
4
5


aws sso login --profile engineering-dev
aws sts get-caller-identity --profile engineering-dev
eval "$(aws configure export-credentials --profile engineering-dev --format env)"
your-legacy-tool
unset AWS_ACCESS_KEY_ID AWS_SECRET_ACCESS_KEY AWS_SESSION_TOKEN

eval executes generated shell text, so use it only with the trusted AWS CLI binary, a fixed or allowlisted profile, and the env format. Do not accept the profile value from untrusted input. Do not echo the output or put it in shell history, a ticket, a .env file, or CI variables.

For a child process, prefer env-no-export output and parse it without logging, or configure a credential_process when the consumer supports the shared AWS config contract. A wrapper should verify the expected account and fail closed before launching the target.

Tradeoffs and lifetime

Environment variables are widely compatible, but every child process inherits them and some diagnostic tools capture environments. A profile provider has a smaller exposure surface and can refresh credentials. Exported role credentials expire no later than their source session, so a long-running process must handle expiration; repeatedly scraping the cache does not solve refresh safely.

Migration checklist

Confirm the tool truly lacks profile, credential_process, web identity, or workload-role support.
Upgrade AWS CLI v2 and configure a named Identity Center profile.
Verify account and ARN with STS.
Export credentials only for the child process or current short-lived shell.
Test expiration and make failures explicit.
Remove copied keys and custom SSO-cache parsing.
Record the legacy exception and an owner/date for eliminating it.

A tighter wrapper pattern

When the tool is invoked from a script, keep exported variables out of the parent shell. Ask the CLI for env-no-export, parse only the three expected names, construct a child environment, start the process without a shell, and discard the map afterward. Reject duplicate or unexpected keys. This is more code than eval, but it prevents later commands in an interactive shell from inheriting the credentials and avoids shell expansion.

Before launch, call STS using the same profile and compare the returned account with a configured account ID. The wrapper should also set a maximum runtime shorter than the remaining session lifetime when the legacy tool cannot refresh credentials. A halfway-completed destructive operation is a poor way to discover expiry.

Audit without collecting secrets: record the tool version, profile name, resolved account and role ARN, start/end time, exit status, and AWS request IDs emitted by the tool. Never record the export output. On incident response, end the Identity Center session and revoke or narrow the permission set as appropriate; deleting a local cache file alone does not undo actions already authorized.

This workaround is best for an interactive migration window. If it becomes a permanent daemon, redesign it around a provider-aware SDK, credential_process, web identity, or a managed AWS compute role.

Verified on 2026-08-01.

Official sources

A Summary of Influence - The Psychology of Persuasion

Yoonsoo Park — Wed, 07 Jun 2023 01:25:00 -0400

In his seminal book, “Influence: The Psychology of Persuasion”, Robert B. Cialdini presents six principles of persuasion that can be leveraged to influence others more effectively. These principles are Reciprocity, Scarcity, Authority, Consistency, Liking, and Consensus. Understanding these principles can help you to persuade others and achieve your goals.

1. Reciprocity

The principle of Reciprocity states that people are more likely to give back the kind of treatment they have received from others.

Example: Imagine you’re working on a software project. You need help from a colleague who is an expert in a particular technology. If you’ve previously helped them when they needed it, they’re much more likely to reciprocate and assist you.

2. Scarcity

The principle of Scarcity posits that people value things more when they are rare or difficult to obtain.

Example: Suppose your company is considering adopting a new software tool. By highlighting that a discount offer for the tool is about to end soon, you can use the scarcity principle to convince your team to make a quicker decision.

3. Authority

The Authority principle suggests that people tend to follow the lead of credible, knowledgeable experts.

Example: If you’re a respected tech lead in your team, your recommendations for code quality improvements are likely to be taken more seriously because of your perceived authority.

4. Consistency

The principle of Consistency holds that people like to be consistent with things they have previously said or done.

Example: If a team member has publicly expressed commitment to improving code quality, they’re more likely to follow through on actions that align with this commitment, such as adopting new coding standards or practices.

5. Liking

The Liking principle argues that people are more likely to be persuaded by people they like.

Example: If you have a good relationship with your project manager, they’re more likely to be persuaded by your proposal to adopt a new project management tool.

6. Consensus

The Consensus principle states that people often look to the actions and behaviors of others to determine their own.

Example: If you can demonstrate that multiple successful software companies are using a particular development methodology, your team might be more likely to adopt that methodology as well.

Wrapping up.

Understanding and leveraging these six principles can greatly enhance your persuasive abilities. Whether you’re negotiating a deal, leading a team, or influencing a decision, these principles can help you achieve your goals.

Cheers! 🍺

When to Use a Sequence Diagram - A Real Life Example

Yoonsoo Park — Tue, 06 Jun 2023 01:25:00 -0400

In the world of software design and development, diagrammatic representations of various processes and functionalities can prove extremely useful. One such useful tool is the Sequence Diagram. It’s a type of interaction diagram found in the Unified Modeling Language (UML). This article sheds light on when to use a sequence diagram, accompanied by a real-life example.

What is a Sequence Diagram?

A sequence diagram, in the context of UML, represents object collaboration and is used to define event sequences between objects for a certain outcome. It emphasizes the time-ordering of messages and allows developers to understand the architecture of the software system visually.

When to Use a Sequence Diagram?

There are several scenarios where a sequence diagram can be particularly helpful:

Designing complex interactions: When you have complex scenarios where several objects interact with each other, sequence diagrams can simplify these interactions by visualizing the message exchange in a sequential order.
Exploring various scenarios: Sequence diagrams can represent multiple scenarios within the same model by using alt (alternative), opt (optional), and loop (iteration) fragments.
Realizing use cases: Sequence diagrams can be used to map out and realize the details of use cases, showing how a system interacts with actors (users or other systems).
Understanding and debugging: They can help in understanding the existing code or in debugging a system as they provide a clear view of the interactions and the sequence of processes.
Protocol or interface modeling: Sequence diagrams can depict the details of a protocol or an interface, helping developers to understand how elements within a system communicate.

Real-Life Example

Let’s consider a real-life example of an online shopping system to understand when and how to use a sequence diagram.

When a customer places an order in an online shopping system, several objects interact with each other. This interaction involves a Customer, ShoppingCart, Payment, and Order objects. A sequence diagram can visualize this process, making it easier to understand.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


Title: Online Shopping Order Sequence

 Customer ShoppingCart Payment Order
 | | | |
 |----1. Add Item to Cart----> |
 | | | |
 |<---2. Confirm Item Added-- |
 | | | |
 |---3. Checkout ----> | |
 | |<---4. Calculate Total
 | | | |
 |----5. Pay ----> |
 | | |<---6. Process Payment
 | | | |
 |<---7. Confirm Payment |
 | | | |
 |----8. Place Order ----> |
 | | |<---9. Process Order
 |<--10. Order Confirmation-- |

In this sequence diagram:

The Customer adds an item to the ShoppingCart.
The ShoppingCart confirms the item has been added.
The Customer checks out, and the ShoppingCart calculates the total cost.
The Customer pays for the items.
The Payment processes the payment and confirms it to the Customer.
The Customer places the order.
The Order processes the order and sends an order confirmation back to the Customer.

Wrapping up!

Sequence diagrams are an integral part of UML, representing

how objects interact in a specific scenario of a use case. They help in simplifying complex interactions, realizing use cases, and understanding the sequence of processes in a system. So, whether you’re designing a new system or debugging an existing one, consider using a sequence diagram to visualize and understand the interactions better.

Deploy a Serverless API Safely with AWS CDK v2

Yoonsoo Park — Mon, 05 Jun 2023 01:25:00 -0400

Older CDK examples often mix @aws-cdk/* v1 modules with aws-cdk-lib, target retired Lambda runtimes, and treat deployment credentials as application configuration. A current workflow uses CDK v2 consistently, an actively supported runtime, temporary operator credentials, and a reviewable synthesized template.

Choose the API deliberately

API Gateway HTTP APIs are usually the lower-cost, lower-complexity choice for Lambda proxy APIs. REST APIs remain appropriate when you need features specific to that product, such as usage plans or certain request transformations. A Lambda Function URL may fit a very small service with simple authorization, while an Application Load Balancer is often a better match for an existing container service.

The following example keeps REST API because it mirrors the older article, but the choice should be explicit.

CDK v2 stack

1
2
3


mkdir current-api && cd current-api
npx aws-cdk@latest init app --language typescript
npm install aws-cdk-lib constructs

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


import { Stack, StackProps, RemovalPolicy } from "aws-cdk-lib";
import { Construct } from "constructs";
import { Runtime, Function, Code } from "aws-cdk-lib/aws-lambda";
import { RestApi, LambdaIntegration } from "aws-cdk-lib/aws-apigateway";
import { Bucket, BlockPublicAccess } from "aws-cdk-lib/aws-s3";

export class ApiStack extends Stack {
 constructor(scope: Construct, id: string, props?: StackProps) {
 super(scope, id, props);

 const bucket = new Bucket(this, "Data", {
 blockPublicAccess: BlockPublicAccess.BLOCK_ALL,
 enforceSSL: true,
 removalPolicy: RemovalPolicy.RETAIN,
 });

 const handler = new Function(this, "Handler", {
 runtime: Runtime.NODEJS_22_X,
 handler: "index.handler",
 code: Code.fromAsset("lambda"),
 environment: { BUCKET_NAME: bucket.bucketName },
 });

 bucket.grantRead(handler);
 const api = new RestApi(this, "Api");
 api.root.addMethod("GET", new LambdaIntegration(handler));
 }
}

grantRead creates a scoped identity policy for the function. It does not mean CDK inferred every permission your code might need. Review the synthesized IAM statements and avoid wildcard grants.

Authenticate, inspect, deploy

1
2
3
4
5
6


aws sso login --profile engineering-dev
AWS_PROFILE=engineering-dev aws sts get-caller-identity
AWS_PROFILE=engineering-dev npx cdk bootstrap
npx cdk synth
npx cdk diff
AWS_PROFILE=engineering-dev npx cdk deploy --require-approval broadening

Bootstrap once per account and Region using an authorized deployment role. Commit cdk.json, source, lockfile, and tests—not cdk.out. Pin the CDK library range and update it deliberately. In CI, use OIDC to assume a deploy role instead of storing access keys.

Production gaps the small example does not solve

Add structured logs, alarms, tracing where justified, throttling, an authorization mechanism, input validation, and an explicit data-retention decision. Package dependencies reproducibly. Test the Lambda handler separately and assert the CDK template for security-sensitive properties. Deploy to a non-production account first and keep rollback behavior clear; retained buckets and databases need their own migration and deletion process.

Migration checklist

Remove CDK v1 service packages and import services from aws-cdk-lib.
Import Construct from constructs.
Select a currently supported Lambda runtime and test the application on it.
Replace explicit keys with Identity Center locally and OIDC/roles in CI.
Run synth, tests, security checks, and diff before deployment.
Inspect IAM broadening and replacement/destruction in the change set.
Verify the deployed endpoint, logs, authorization, S3 access, and rollback.

CDK gives higher-level constructs and reusable TypeScript, but CloudFormation or SAM may be simpler when the infrastructure is small, while Terraform/OpenTofu may fit a multi-provider estate. Choose based on team ownership and lifecycle, not language preference alone.

Test the infrastructure contract

CDK assertions catch regressions before CloudFormation receives them. A focused test should verify properties whose accidental removal would change the security or durability boundary: supported runtime, private bucket, TLS enforcement, retention policy, and narrow grants. Do not snapshot the entire synthesized template; broad snapshots are noisy and reviewers often approve them without understanding a changed IAM statement.

After deployment, invoke the endpoint with an authorized and unauthorized caller, inspect the function logs, put a known object in the bucket, and confirm the function can read it but cannot write or list unrelated buckets. Then exercise rollback from a deliberately broken application version. CloudFormation rollback does not automatically reverse data migrations, so keep stateful changes separate from routine function deployment.

If the API is internet-facing, add an explicit abuse plan: route throttles, account concurrency protection, payload limits, WAF only where its rules solve a known threat, and cost alarms. If it is internal, verify the resource policy, authorizer, DNS, and network path from the real caller. “The stack deployed” is only a structural check; it does not prove the API is operable or appropriately authorized.

Verified on 2026-08-01.

Official sources

Story or Die - How to Use Brain Science to Engage, Persuade, and Change Minds in Business and in Life Summary

Yoonsoo Park — Sun, 04 Jun 2023 01:25:00 -0400

In the book “Story or Die: How to Use Brain Science to Engage, Persuade, and Change Minds in Business and in Life”, the author delves into the fascinating connection between brain science, storytelling, and effective communication. Drawing insights from neuroscience, the book explores why storytelling is a powerful tool to engage, persuade, and ultimately change minds.

1. The Power of Storytelling and the Brain

Neuroscientist Michael Gazzaniga suggests that our brains primarily evaluate decisions in terms of approaching or withdrawing from a situation. This fundamental aspect of brain functioning underlines the importance of feeling safe when making choices. Consequently, the pursuit of psychological safety becomes crucial in effective communication within organizations.

2. Psychological Safety and the Need for Safety

Maintaining psychological safety is essential for individuals and organizations. People are wired to avoid threats to their safety, and they prioritize safety over abstract, conceptual, or neutral facts. Even if presented with important information, if it is perceived as a threat to their safety, individuals are likely to resist it.

3. The Role of Facts and Persuasion

Facts alone may not be sufficient for persuasion. To capture attention and achieve persuasion, facts need to clearly demonstrate the outcomes and benefits they bring, not only in terms of safety but also personal growth. When individuals are convinced that accepting a more correct opinion, despite contradicting their own beliefs, is safer, they become more open to accepting alternative viewpoints.

4. Overcoming Resistance and Instinctual Knowledge

Resistance to new ideas or facts stems from an instinctual knowledge that changing the current state can have potentially negative consequences. It is important to understand that people’s resistance to change is not due to intellectual deficiencies or flawed personalities but rather an inherent instinct for self-preservation.

5. The Role of Leaders and Organizations

True leaders and organizations should focus on creating an environment where individuals feel safe to change their thoughts and opinions. Encouraging others to recognize that adopting more accurate perspectives not only ensures their safety but also benefits them personally can foster open-mindedness and growth.

Wrapping up!

In conclusion, “Story or Die: How to Use Brain Science to Engage, Persuade, and Change Minds in Business and in Life” highlights the significance of storytelling and psychological safety in effective communication. By understanding the neuroscience behind decision-making and the need for safety, individuals and organizations can harness the power of storytelling to engage, persuade, and ultimately change minds.

Cheers! 🍺

Creating an Empty Commit in GitHub

Yoonsoo Park — Sat, 03 Jun 2023 01:25:00 -0400

When working with Git and GitHub, commits serve as important milestones that capture meaningful changes in your codebase. However, there may be situations where you need to create an empty commit without any actual code changes. (what if you need to trigger a Semantic Release by commiting.) Although GitHub’s user interface doesn’t provide a direct option to create an empty commit, you can achieve this through Git commands.

Creating an Empty Commit

To create an empty commit, use the following Git command:

1

git commit --allow-empty -m "Empty commit"

The --allow-empty flag allows creating a commit without any changes. The -m option is used to provide a commit message. Replace "Empty commit" with a meaningful message for your empty commit.

Pushing the Empty Commit

To push the empty commit to the remote repository, run the following command:

1

git push origin <branch-name>

Replace <branch-name> with the name of the branch where you want to push the empty commit.

Conclusion

Even though GitHub’s user interface doesn’t offer a direct option to create an empty commit, you can achieve this by utilizing Git commands. By following the steps outlined in this article, you can successfully create an empty commit and push it to your remote repository. Empty commits can be useful in certain scenarios, such as triggering build processes or signaling specific events in your version control history. Remember to use them judiciously and ensure that your commit history accurately reflects the changes in your codebase.

Create Salesforce Scratch Org Users with sf CLI

Yoonsoo Park — Fri, 02 Jun 2023 01:25:00 -0400

Verified on 2026-08-01. Generic User DML assembled through shell substitution is fragile and unsafe; required fields, profiles, and licenses vary by org.

For a scratch org, use the purpose-built command:

1
2
3


sf org create user --target-org scratch \
 --set-alias qa-user email=qa@example.invalid lastname=Tester
sf org assign permset --name App_Tester --target-org qa-user

Keep user definitions free of real personal data and grant permissions through reviewed permission sets. Scratch-user creation is reproducible and scoped to disposable development orgs. Production user provisioning is a different administrative lifecycle: use your identity/provisioning system or a reviewed API integration with license, profile, MFA, deactivation, and audit controls.

Migration: delete jq command substitution, move nonsecret defaults to a user definition, create in a fresh scratch org, verify sf org list users, then test the intended permission set.

Reference: Salesforce CLI org commands.

Current mental model

A scratch-org user is a disposable test identity derived from licenses and profiles available in that org. It is not a shortcut for production identity lifecycle management. The CLI command understands scratch-user defaults and avoids turning JSON into unquoted shell arguments.

Step-by-step safe example

Confirm the org, inspect existing users, create a narrowly scoped identity, and assign permission sets separately:

1
2
3
4
5
6


sf org display --target-org scratch
sf org list users --target-org scratch
sf org create user --target-org scratch --set-alias qa-user \
 email=qa@example.invalid lastname=Tester
sf org assign permset --name App_Tester --target-org qa-user
sf org display user --target-org qa-user

Use reserved invalid domains for synthetic addresses unless email delivery is part of the test. Never place real employee details or passwords in a committed definition. Permission sets make intent reviewable and avoid cloning an overprivileged profile. If the requested license or profile is unavailable, change the scratch definition or test design rather than borrowing an administrator identity.

Alternatives and tradeoffs

Inline attributes are quick for one user. A versioned user-definition file is reproducible for a team but must contain only nonsecret synthetic data. Apex or REST creation offers custom logic, yet it exposes org-specific required fields and licensing rules. Production and long-lived sandbox users should come from an identity governance or provisioning process with approval, MFA, deactivation, and auditability.

Migration and verification checklist

Remove $(jq ...) and other shell-expanded field lists.
Separate identity creation from permission assignment.
Replace personal sample data with synthetic values.
Recreate the user in a fresh scratch org to test reproducibility.
Log in as that user and exercise the intended feature, including denied actions.
Delete the scratch org at the end rather than carrying test identities forward.

Verification is behavioral: listing the user proves creation, while tests under that identity prove the permission boundary.

Tier vs Layer - Understanding the Organization of Software Architecture

Yoonsoo Park — Thu, 01 Jun 2023 01:25:00 -0400

In software architecture, the concepts of “tier” and “layer” play a crucial role in organizing and structuring complex systems. While often used interchangeably, understanding the distinctions between these terms is essential for designing scalable and maintainable applications. Let’s explore the difference between tiers and layers using a fictional e-commerce platform as an example.

Tiers: Dividing the Application Stack

Tiers refer to logical or physical divisions within an application stack based on functionality or deployment. They represent distinct layers that provide specific services and capabilities. In our e-commerce platform example, we can identify three primary tiers:

Presentation Tier: This tier handles the user interface and interaction. It includes components like web or mobile interfaces, user authentication, and front-end frameworks. Its primary responsibility is to deliver a visually appealing and user-friendly experience.
Application Tier: Also known as the business logic tier, this layer contains the core application logic. It encompasses functionalities such as product catalog management, order processing, and payment integration. The application tier coordinates and orchestrates the various operations required to run the e-commerce platform smoothly.
Data Tier: This tier focuses on data storage and retrieval. It includes databases, data caching mechanisms, and data access layers. In our example, the data tier would store information about products, customer details, and order history. It ensures reliable and efficient data management.

Layers: Modular Groupings within Tiers

Layers, on the other hand, are modular groupings or abstractions of components within a specific tier. They provide a structured approach to organizing functionalities and responsibilities. Let’s examine the layers within each tier of our e-commerce platform:

Presentation Tier Layers

User Interface Layer: This layer encompasses the visual elements and user interaction components. It includes HTML, CSS, JavaScript, and front-end frameworks like React or Angular. Its responsibility is to provide an engaging and intuitive user interface.
Authentication Layer: This layer focuses on user authentication and authorization mechanisms. It ensures secure access control and safeguards user accounts from unauthorized access.

Application Tier Layers

Product Management Layer: This layer handles product-related functionalities such as catalog management, inventory tracking, and pricing. It orchestrates the logic for creating, updating, and displaying product information.
Order Processing Layer: This layer manages the end-to-end order processing flow, including cart management, payment integration, and shipping coordination. It ensures accurate and timely order fulfillment.

Data Tier Layers

Database Layer: This layer represents the underlying database management system (DBMS) responsible for data storage and retrieval. It includes database technologies like MySQL, PostgreSQL, or MongoDB.
Data Access Layer: This layer provides an abstraction over the database and handles interactions with the data. It encapsulates queries, data validation, and caching mechanisms, ensuring efficient and secure data access.

Conclusion

Understanding the distinctions between tiers and layers in software architecture is vital for designing scalable, modular, and maintainable systems. Tiers represent logical or physical divisions based on functionality, while layers provide structured groupings within each tier. By effectively organizing components into tiers and layers, developers can build robust and well-structured applications.

Understanding the Differences Between IaaS, FaaS, and PaaS in Cloud Computing

Yoonsoo Park — Wed, 31 May 2023 01:25:00 -0400

IaaS, PaaS, and FaaS describe different operational boundaries. The useful question is not which acronym is most modern, but which responsibilities a team should own for a particular workload.

Infrastructure as a Service (IaaS)

IaaS provides compute, storage, and networking primitives while leaving the guest operating system and application stack to the customer.

Amazon EC2, Azure Virtual Machines, and Google Compute Engine are familiar examples. This model fits workloads that require operating-system control, specialized networking, custom agents, or software that does not fit a managed platform. That control also brings patching, image management, capacity planning, and host-level observability.

Function as a Service (FaaS)

FaaS runs event-driven functions without asking the application team to provision servers. AWS Lambda, Azure Functions, and Google Cloud Functions are examples.

FaaS is one form of serverless computing, not a synonym for every serverless service. It fits short-lived, event-oriented work with variable demand. Teams still own code, dependency security, concurrency behavior, retries, idempotency, observability, and service limits. Long-running processes, specialized runtimes, or predictable sustained loads may fit another compute model better.

Platform as a Service (PaaS)

PaaS accepts an application or container and manages more of the runtime, deployment, routing, health, and scaling layer. Elastic Beanstalk, Azure App Service, and Google App Engine are examples, although current managed-container services also occupy similar territory.

PaaS is useful when a team wants a conventional long-running application without owning hosts or building an orchestration platform. The tradeoffs are platform constraints, less control over the runtime, service-specific deployment behavior, and possible migration cost.

Choose by responsibility

Question	IaaS	PaaS or managed containers	FaaS
Need guest OS control?	Strong fit	Usually no	No
Conventional long-running service?	Possible, more operations	Strong fit	Usually not
Event-driven, bursty execution?	Possible, more capacity work	Possible	Strong fit
Team owns patching the guest OS?	Yes	Usually no	No
Main constraints	Operations and capacity	Platform contract	Runtime, duration, concurrency, event semantics

Real systems commonly mix these models. A web application might run on a managed container platform, use functions for asynchronous event handling, and retain a small VM for software that requires host access. Decide per component using latency, execution duration, scaling pattern, compliance, portability, team skills, failure recovery, and total operational cost.

The service-model definitions remain useful, but provider catalogs increasingly form a spectrum rather than three clean boxes. Document the responsibility boundary for the selected service instead of relying on the acronym alone.

References: NIST SP 800-145, The Definition of Cloud Computing and AWS Cloud Adoption Framework: platform perspective. Verified 2026-08-01.

Guiding Interns in Your Team

Yoonsoo Park — Tue, 30 May 2023 01:25:00 -0400

As a seasoned professional, it is important to understand the significance of guiding interns effectively within your team. Internships provide valuable learning opportunities, and by offering guidance, you can help shape their professional growth. In this article, we will explore some insightful advice inspired by famous books that can serve as a guiding light in mentoring interns.

1. “The Alchemist” by Paulo Coelho: Unleash their Potential

Just as the protagonist Santiago embarks on a transformative journey, your intern is also at the beginning of their career voyage. Approach your role as a mentor with the mindset of an alchemist. Recognize the untapped potential within them and help them discover their unique strengths. Encourage them to experiment with different tasks, departments, and roles, allowing them to unearth their passions and interests.

2. “The Lean Startup” by Eric Ries: Embrace the Iterative Process

Eric Ries emphasizes the importance of an iterative approach in startups, and this principle can be applied to guiding interns as well. Encourage them to adopt a mindset of continuous learning and improvement. Provide regular feedback and set short-term goals, enabling them to make incremental progress. Emphasize that failures are stepping stones to success, and that learning from mistakes is an integral part of professional growth.

3. “Quiet: The Power of Introverts in a World That Can’t Stop Talking” by Susan Cain: Nurture Diverse Talents

Interns come from diverse backgrounds, and it is essential to recognize and appreciate the unique talents they bring to the team. Drawing inspiration from Susan Cain’s book, understand that introverted individuals may possess exceptional analytical skills and a propensity for introspection. Create an inclusive environment that caters to different personalities, allowing interns to thrive and contribute in their own unique way.

4. “The 7 Habits of Highly Effective People” by Stephen R. Covey: Foster Independence and Proactivity

In Stephen R. Covey’s timeless book, he shares seven habits that lead to success. Two key habits, “Be Proactive” and “Begin with the End in Mind,” are particularly relevant when guiding interns. Encourage them to take ownership of their work and projects. Set clear objectives and allow them to devise their own plans to achieve those goals. This approach fosters independence, responsibility, and a sense of accountability.

5. “The Art of War” by Sun Tzu: Cultivate a Supportive Environment

Sun Tzu’s ancient treatise on warfare provides valuable insights on leadership and strategy. While the battlefield might seem far removed from the office, the concept of fostering a supportive environment applies universally. Be a mentor who leads by example, offering guidance and support while allowing interns to learn from their experiences. Create an atmosphere that encourages open communication, collaboration, and camaraderie among team members.

Conclusion

Guiding interns effectively requires patience, empathy, and an understanding of their unique needs and aspirations. By incorporating lessons from famous books into your mentoring approach, you can inspire and empower interns to reach their full potential. Remember, as a mentor, your guidance can have a profound impact on shaping their future careers. Embrace this opportunity to make a positive difference and create a legacy that extends far beyond their time as interns.

Note: The book references mentioned in this article serve as metaphors and sources of inspiration for guiding interns, and their concepts should be adapted and applied in a manner appropriate to the professional context.

Cheers! 🍺

The Pragmatic Programmer; Bend or Break

Yoonsoo Park — Mon, 29 May 2023 01:25:00 -0400

Bend or Break: Embracing Adaptability

The Bend-or-Break principle encourages software developers to be flexible and adaptable in the face of changing requirements, technologies, and project circumstances. Instead of clinging rigidly to predefined plans or solutions, this philosophy emphasizes the need to adjust, iterate, and overcome challenges by bending existing strategies or breaking away from them altogether.

Real-Life Examples

Mobile Application Development: Consider a team developing a mobile application for a startup. During the initial planning phase, they decide to build the app for a specific platform. However, as the project progresses, they realize that the target market prefers a different platform. To adapt, the team must be willing to break away from their original plan and pivot towards the new platform, rather than persisting with a less suitable solution.
Agile Development: Agile methodologies, such as Scrum, embody the bend-or-break philosophy. Agile teams embrace change and regularly adapt their plans based on customer feedback and evolving requirements. They recognize that being rigid and unwilling to adjust can hinder progress and limit the potential for delivering valuable software.
Software Maintenance: When maintaining legacy systems, developers often encounter outdated technologies or code that no longer aligns with modern best practices. To ensure the continued functionality and improvement of the system, developers must be willing to bend the existing codebase, refactoring and modernizing it over time, or even breaking away from it completely and rebuilding certain components to ensure scalability and maintainability.

The Benefits of Adaptability

Embracing the bend-or-break mindset offers several advantages to software developers and teams:

Resilience: Adaptability enables programmers to navigate unexpected challenges and respond effectively to shifting circumstances. By bending or breaking, developers can overcome obstacles, meet evolving requirements, and deliver valuable solutions.
Innovation: Flexibility allows developers to explore new technologies, frameworks, and methodologies. By being open to change, they can experiment, learn, and leverage emerging trends to create innovative solutions that better meet user needs.
Continuous Learning: Adapting to change necessitates acquiring new knowledge and skills. The bend-or-break philosophy promotes a culture of continuous learning, empowering developers to expand their expertise and stay up-to-date with advancements in the field.
Delivering Value: By embracing adaptability, developers can deliver software that better aligns with user expectations and market demands. Being responsive to change increases the likelihood of delivering timely, relevant, and high-quality products.

Wrapping up

In the fast-paced world of software development, the bend-or-break philosophy outlined in “The Pragmatic Programmer” is crucial. Embracing adaptability allows programmers to thrive amidst changing requirements, emerging technologies, and evolving project circumstances. By being willing to bend existing plans and strategies or break away from them when necessary, developers can foster resilience, drive innovation, embrace continuous learning, and ultimately deliver valuable software solutions.

Cheers! 🍺

The Pragmatic Programmer; A Pragmatic Approach

Yoonsoo Park — Sun, 28 May 2023 01:25:00 -0400

In The Pragmatic Programmer, Andrew Hunt and David Thomas present a wealth of wisdom and practical guidance for software developers. Section 3 of the book, titled “A Pragmatic Approach,” dives into the essence of pragmatic programming and how it can revolutionize the way we approach software development.

Embracing Pragmatic Programming

A pragmatic approach to software development revolves around practicality, effectiveness, and adaptability. It encourages programmers to go beyond following strict methodologies and instead focus on finding practical solutions that deliver value to users. Let’s explore the key principles and practices that define a pragmatic approach.

Deadlines as Opportunities

Pragmatic programmers view deadlines not as constraints, but as opportunities for prioritization and delivering incremental value. By embracing realistic deadlines, developers can focus on delivering the most critical features first and iterating on their work over time. This approach allows for faster feedback cycles and aligns development efforts with user needs.

Maintainable Code: The Golden Rule

Writing maintainable code lies at the core of a pragmatic approach. Pragmatic programmers recognize that code is read more often than it is written. They prioritize writing clear, well-structured code that is easy to understand and modify. By considering future maintainers of the codebase, they ensure long-term productivity and reduce technical debt.

Debugging: Thinking Outside the Box

When facing software bugs, a pragmatic programmer employs a systematic and creative approach to debugging. They go beyond simply fixing the immediate symptom and strive to understand the underlying cause. Techniques like rubber duck debugging, where programmers explain their code to an inanimate object, help uncover hidden issues and encourage problem-solving from different perspectives.

Automation: Working Smarter, Not Harder

Automation is a cornerstone of pragmatic programming. By automating repetitive tasks and building efficient workflows, developers can save time and reduce errors. Whether it’s automating code formatting, setting up continuous integration pipelines, or creating scripts for deployment, automation empowers programmers to work smarter and focus on higher-value activities.

Pragmatic Testing: Balancing Coverage and Efficiency

Testing is a vital component of pragmatic programming. Pragmatic programmers aim for a balanced approach to testing, seeking an optimal trade-off between coverage and efficiency. They prioritize critical tests and focus on generating meaningful test cases that cover a wide range of scenarios, while avoiding excessive redundancy that could hamper development speed.

Revolutionizing Software Development with a Pragmatic Approach

A pragmatic approach to software development enables programmers to adapt, evolve, and thrive in the ever-changing landscape of technology. By embracing practicality, maintaining code quality, employing effective debugging techniques, leveraging automation, and adopting a balanced testing strategy, developers can deliver high-quality software that meets user needs while maximizing efficiency.

Let us embark on this journey of pragmatic programming, where innovation and practicality go hand in hand, and software development becomes a delightful and productive endeavor.

Cheers! 🍺

The Pragmatic Programmer; A Pragmatic Philosophy

Yoonsoo Park — Sat, 27 May 2023 01:25:00 -0400

The Pragmatic Programmer is a renowned book written by Andrew Hunt and David Thomas, offering valuable insights and practical advice for software developers. In Section 2 of the book, titled “A Pragmatic Philosophy,” the authors introduce a mindset and set of principles that form the foundation of a pragmatic approach to programming. Let’s explore this philosophy and its real-life applications.

The Cat Ate My Source Code

One key aspect of the pragmatic philosophy is taking responsibility for our work. It’s easy to blame external factors or circumstances when things go wrong, but a pragmatic programmer acknowledges their role in the development process. For example, imagine a software developer who encounters a bug in their code. Instead of blaming the lack of clear requirements or time constraints, they focus on understanding and rectifying the issue, taking ownership of their codebase.

Software Entropy: The Constant Battle

Software entropy refers to the tendency of software systems to become more complex and disorganized over time. A pragmatic programmer recognizes the need to combat entropy through regular code maintenance, refactoring, and clean-up efforts. Consider a scenario where a development team notices their codebase becoming difficult to maintain due to increasing complexity. They adopt a pragmatic approach by scheduling regular refactoring sessions and implementing automated tests to catch regressions, thereby managing and reducing software entropy.

Stone Soup and Boiled Frogs: The Power of Incremental Change

The metaphors of stone soup and boiled frogs illustrate the value of incremental change. In software development, making small, meaningful improvements over time can lead to substantial progress. For instance, imagine a project manager who wants to introduce a new development process to improve team efficiency. Instead of imposing a drastic change overnight, they take a pragmatic approach by gradually introducing small process tweaks, encouraging feedback from the team, and iteratively refining the process based on real-world outcomes.

Good Enough Software: Balancing Perfectionism and Pragmatism

The pursuit of perfection can hinder progress in software development. The pragmatic philosophy suggests focusing on delivering “good enough” software that meets current requirements while maintaining a high level of quality. For instance, imagine a startup developing a minimum viable product (MVP) to test its viability in the market. Instead of spending excessive time on refining every feature, they adopt a pragmatic approach by prioritizing core functionality and delivering a working product within the available resources and timeframe.

Your Knowledge Portfolio: Investing in Continuous Learning

A pragmatic programmer understands the importance of continually expanding their knowledge and skills. They treat their professional development as an investment portfolio, diversifying their expertise and regularly updating existing skills. For example, a software developer may invest time in learning a new programming language or exploring emerging technologies that align with their career goals. By maintaining an up-to-date knowledge portfolio, they remain adaptable and valuable in a rapidly evolving industry.

We will read the Section 3, A Pragmatic Approach, tomorrow.

Cheers! 🍺

A Summary of Surrounded by Idiots by Thomas Erikson

Yoonsoo Park — Fri, 26 May 2023 01:25:00 -0400

Alright, listen up aspiring code nerds! (in a good way ;) If you want to rock the software engineering realm, there’s a crucial superpower you gotta wield: communication skills! Even if you couldn’t care less about the crazy lives of your fellow humanoids, you simply can’t dodge the inevitable communication or chit-chat. So, brace yourselves, folks! Embrace the unavoidable art of conversation like a true champ, or prepare to be stuck in an eternal bug-fixing abyss.

Understanding and Applying the Four Main Communication Styles: Red, Yellow, Green, and Blue

In the international bestseller “Surrounded by Idiots,” Thomas Erikson provides a unique perspective on understanding and dealing with different communication styles. Grounded in the DISC behavioral assessment tool, Erikson assigns colors to these styles: Red, Yellow, Green, and Blue. This system allows for a more effective approach to interpersonal communication.

1. Red (Dominance)

Red individuals are characterized by their determination, strong will, and ability to maintain control. They are dynamic, active, and task-oriented.

Key traits:

Decisive: They make quick decisions and are driven by power and control.
Goal-oriented: Reds thrive on challenges and are often competitive.
Impatient: They prefer quick actions and results.

Communication style:

Reds prefer direct, clear, and to-the-point communication. They value efficiency and may become impatient with lengthy discussions.

When communicating with Red individuals, clarity and brevity are key. State your points in a structured, concise manner, focusing on the results or outcomes. Avoid giving too many details or lengthy explanations.

2. Yellow (Influence)

Yellow individuals are sociable, expressive, and dynamic. They thrive in environments where interaction and socializing are encouraged.

Key traits:

Enthusiastic: Yellows are often the life of the party, bringing energy and positivity wherever they go.
Persuasive: They excel at influencing and inspiring others.
Optimistic: Yellows often see the brighter side of things, maintaining a positive outlook.

Communication style:

Yellows enjoy interactive and engaging communication. They enjoy storytelling and use humor frequently.

When communicating with Yellow individuals, adopt an engaging, positive, and friendly approach. Avoid being overly formal or negative. Yellows prefer exciting ideas, stories, and an energetic tone.

3. Green (Steadiness)

Green individuals prioritize relationships and are patient, supportive, and relaxed. They value cooperation and prefer a peaceful environment.

Key traits:

Reliable: Greens are dependable and consistent.
Patient: They are tolerant and tend to avoid conflicts.
Team-oriented: Greens work well in a team setting, prioritizing group harmony.

Communication style:

Greens communicate in a calm, patient manner, preferring to listen first and speak second. They value relationships and focus on understanding others’ viewpoints.

When communicating with Green individuals, demonstrate patience, understanding, and empathy. Show genuine interest in their thoughts and feelings. Avoid aggression, confrontation, or a rushed approach.

4. Blue (Conscientiousness)

Blue individuals are analytical, meticulous, and systematic. They value accuracy and logic.

Key traits:

Analytical: Blues prefer to thoroughly examine information before making decisions.
Detail-oriented: They pay careful attention to details and value precision.
Systematic: Blues follow specific processes or systems.

Communication style:

Blues communicate in a logical, systematic manner. They prefer facts, details, and well-structured arguments.

When communicating with Blue individuals, be analytical, logical, and accurate. They appreciate facts and precise details. Be prepared to answer questions and provide evidence for your statements. Avoid emotional arguments, ambiguity, or inconsistency.

Wrapping up.

Understanding these four communication styles can greatly improve your interpersonal relationships and effectiveness at work. However, keep in mind that these are guidelines, and real people may exhibit traits from several colors. The objective is to make your interlocutor feel understood, respected, and comfortable during the conversation by adapting your communication style to theirs.

Now, if you can categorize your co-workers into these convenient color compartments, congratulations, you’ve passed Communication 101. But don’t pop the champagne yet, that’s just the beginning. Keep stuggling until you master it.

Cheers! 🍺

The Rules of Work by Richard Templar

Yoonsoo Park — Thu, 25 May 2023 01:25:00 -0400

The Rules of Work is a practical guide by Richard Templar. It is composed of 108 rules that guide professionals in navigating their work lives more efficiently and effectively. In this summary, we will highlight some of the key points that Templar emphasizes in his influential work.

Introduction

Templar’s book offers a fresh perspective on the unspoken rules that dictate success in the workplace. The author’s rules are intended to make one more professional, confident, and ultimately, more successful at work. The book is divided into ten parts, each highlighting different facets of the workplace.

Walk Your Talk

Get your work noticed.
Never stand still.
Volunteer carefully.
Carve out a niche for yourself.
Under promise and over deliver.

Know That You’re Being Judged at All Times

Cultivate a smile.
Dress well.
Cultivate the art of speech.
Be aware of personal space.
Practice being liked.

Have a Plan

Know what you want long term.
Know what you want short term.
Study the promotion system.
Develop a game plan.
Set objectives.

If You Can’t Say Anything Nice, Shut Up

Don’t gossip.
Be cheerful and positive.
Keep your personal life to yourself.
Be a good listener.
Only speak sense.

Look After Yourself

Know the ethics of your industry.
Know the legalities of your industry.
Set personal standards.
Have positive personal ambitions.
Be physically fit.

Blend In

Know the corporate culture.
Speak the language.
Dress up or down accordingly.
Be adaptable in your dealings with different people.
Know where to hang out, and when.

Act One Step Ahead

Dress one step ahead.
Talk one step ahead.
Act one step ahead.
Think one step ahead.
Address corporate issues and problems one step ahead.

Cultivate Diplomacy

Know the system — and milk it.
Be wise with information.
Beware of the office politics.
Be discreet.
Cultivate the friendship and respect of your colleagues.

Know the Rules About Authority

Understand the hierarchy.
Know who the real bosses are.
Know the people who know the people.
Never disapprove of others.
Understand the role of the job.

Play the Game

Know that we’re all playing a game.
Be enthusiastic.
Be a ‘can-do’ person.
Be 100% committed.
Maintain a sense of humor.

Look Out for the Future

Know the business you’re in.
Constantly reassess your position.
Know where you want to go.
Make sure your manager knows you want to progress.
Study the industry.
Study the competition.
Study your organization.
Study your department.
Study your job.
Know the skills of the future and acquire them.

Know When to Break the Rules

Know which rules to break.
Be subtle.
Bend the rules, don’t break them.
Make sure breaking the rule benefits the company.
Don’t get caught.
Do it with humor.
Know the exceptions to the rule.
Know that there’s always an exception to the rule.
Be paradoxical.
If in doubt, don’t.

Be Good at PR

Know the benefits of networking.
Create a network.
Maintain your network.
Use your network.
Enjoy your network.
Be known for one thing.
Self-publicize.
Project a consistent image.
Make sure your manager knows how good you are.
Be modest.

Know the System

Understand the company’s philosophy.
Learn the unspoken rules.
Know the rules about the money.
Know the rules about communicating.
Know the rules about sex.
Know the rules about company property.
Know what gets rewarded.
Know what doesn’t get rewarded.
Know when to stand by the rules.
Know when to ignore them.

Don’t Push Too Hard

Don’t badmouth the competition.
Don’t badmouth the company.
Don’t whine.
Don’t rely on one ally.
Don’t hide behind your job description.
Don’t have favorites.
Don’t be irreplaceable.
Don’t carry tales.
Don’t rely on status.
Don’t push your luck.

Know the Tricks

Watch for game players.
Identify the company politics.
Be aware of personal agendas.
Beware of the insecure.
Watch out for the ambitious.
Understand power structures.
Recognize power plays.
Know when to leave.

Conclusion

The Rules of Work presents a pragmatic and effective roadmap for professional success. It provides guidance on how to behave, how to look, and how to navigate workplace dynamics effectively. Templar’s rules are not about manipulating others, but about helping professionals become adept at working within the corporate culture to their advantage.

In essence, Templar’s advice is centered around becoming a good team player, maintaining professionalism, and balancing work with a healthy lifestyle. It’s a must-read for anyone serious about making a mark in their professional life.

“It’s all a game, and the Rules of Work are the rules of the game. We all have to go to work, and we all play the game. The winners will be the ones who are very good at playing the game professionally,” - Richard Templar.

Cheers! 🍺

Walking the Directory and Creating a TreeNode

Yoonsoo Park — Wed, 24 May 2023 01:25:00 -0400

A non-blocking traversal for new code

For new code, prefer fs.promises.readdir(path, { withFileTypes: true }) so traversal does not block the event loop or call stat for every entry. Decide explicitly how to handle symbolic links, permission errors, cycles, and paths that disappear during traversal.

Walking the Directory and Creating a TreeNode in Node.js

In this article, we will be exploring how to navigate or walk through a file directory in Node.js, creating a TreeNode for each file or subdirectory we encounter. This will involve using Node’s built-in fs (file system) and path modules, as well as the crypto module for hashing file contents.

First, let’s begin by creating an interface for our file metadata:

1
2
3
4
5


interface FileMetadata {
 path: string;
 isDirectory: boolean;
 hash?: string;
}

Here, our FileMetadata interface defines three properties: path (the file or directory path), isDirectory (a boolean indicating if the path is a directory), and hash (a string representing a file hash, which will be optional since directories won’t have a hash).

Next, we create a TreeNode class:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


class TreeNode {
 metadata: FileMetadata;
 children: TreeNode[];

 constructor(metadata: FileMetadata, children: TreeNode[] = []) {
 this.metadata = metadata;
 this.children = children;
 }

 print(level: number = 0): void {
 console.log(' '.repeat(level * 2) + (this.metadata.isDirectory ? 'Dir: ' : 'File: ') + this.metadata.path);
 for (let child of this.children) {
 child.print(level + 1);
 }
 }
}

The TreeNode class represents a node in our tree structure. Each node contains metadata (of type FileMetadata) and an array of child nodes (children). The print method allows us to print the path of the node and its children, with indentation to represent the depth in the tree.

We’ll need a method to hash a file’s content. For this, we use Node.js’s built-in crypto module:

1
2
3
4
5
6


async function hashFile(file: string): Promise<string> {
 const fileBuffer = await fs.promises.readFile(file);
 const hashSum = crypto.createHash('sha256');
 hashSum.update(fileBuffer);
 return hashSum.digest('hex');
}

The hashFile function reads a file without blocking the event loop, then computes a SHA-256 digest. For very large files, use a stream instead of buffering the entire file.

Finally, we create the walkDir function:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19


async function walkDir(currentPath: string): Promise<TreeNode> {
 const stat = await fs.promises.lstat(currentPath);
 if (stat.isSymbolicLink()) {
 throw new Error(`Symbolic links are not followed: ${currentPath}`);
 }
 if (!stat.isDirectory()) {
 return new TreeNode({
 path: currentPath,
 isDirectory: false,
 hash: await hashFile(currentPath),
 });
 }

 const entries = await fs.promises.readdir(currentPath, { withFileTypes: true });
 const children = await Promise.all(
 entries.map(entry => walkDir(path.join(currentPath, entry.name)))
 );
 return new TreeNode({ path: currentPath, isDirectory: true }, children);
}

The traversal rejects symbolic links instead of following them outside the requested tree or entering a cycle. Decide whether permission and disappearance errors should stop the walk or be represented in the result. Promise.all can open too many files in a very large tree, so production crawlers should add a concurrency limit.

This produces a useful tree for a controlled directory. It is not a replacement for a version-control object model: files can change during the walk, metadata is platform-dependent, and a stable snapshot requires additional consistency rules.

Use IAM Identity Center Profiles Safely from TypeScript

Yoonsoo Park — Tue, 23 May 2023 01:25:00 -0400

AWS Single Sign-On was renamed AWS IAM Identity Center. More importantly, application code no longer needs to launch aws sso login through a shell or extract credentials itself. AWS CLI v2 performs the interactive login; the AWS SDK for JavaScript v3 resolves and refreshes the resulting temporary credentials.

Configure and authenticate

1
2
3


aws configure sso --profile engineering-dev
aws sso login --profile engineering-dev
aws sts get-caller-identity --profile engineering-dev

Modern CLI configuration normally contains a reusable sso-session section plus a profile that selects the account and permission set. Let the CLI write this structure. Do not depend on its exact cache-file layout: it is an implementation detail, can contain multiple sessions, and is not an application API.

Login is deliberately interactive. Keep it outside a server process and outside a web request handler. A program that interpolates an untrusted profile name into exec("aws sso login ...") also creates command-injection risk.

Use the v3 provider chain

Install only the service client you use and the credential provider package:

1

npm install @aws-sdk/client-sts @aws-sdk/credential-providers

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12


import { STSClient, GetCallerIdentityCommand } from "@aws-sdk/client-sts";
import { fromIni } from "@aws-sdk/credential-providers";

const profile = process.env.AWS_PROFILE ?? "engineering-dev";

const sts = new STSClient({
 region: process.env.AWS_REGION ?? "us-east-1",
 credentials: fromIni({ profile }),
});

const identity = await sts.send(new GetCallerIdentityCommand({}));
console.log({ account: identity.Account, arn: identity.Arn });

fromIni supports profiles that use IAM Identity Center and profiles that assume another role from that source. For a simple service client, the Node.js default provider chain is often enough: set AWS_PROFILE and omit credentials entirely. fromSSO is useful when the selected profile itself is an SSO profile, but fromIni is more flexible for role chaining.

Never log the resolved credential object. The access key, secret key, and session token are short-lived, but still authorize requests until they expire.

Local people and deployed workloads are different

Identity Center profiles are intended for workforce tools and local development. Code deployed to Lambda, ECS, EC2, or EKS should use its workload role through the default provider chain. CI should prefer OIDC federation. A server must not depend on a developer’s browser session or home-directory cache.

Failure handling

If the session expired, the SDK error should tell the operator to run aws sso login --profile ...; the application should not silently switch to another profile. Validate the resolved account before destructive operations. Avoid default for scripts that can change infrastructure, because an implicit profile makes account mistakes harder to see.

Migration checklist

Upgrade from the monolithic aws-sdk v2 package to modular v3 clients.
Replace embedded keys and custom cache parsing with the default provider chain or fromIni.
Move interactive login to an explicit operator step.
Validate account and ARN with STS before changes.
Replace shell-string execution with SDK calls; if a CLI process is unavoidable, use argument arrays and an allowlisted profile.
Test expiry and re-login behavior, role chaining, and a wrong-account guard.

Tradeoff: profile-based authentication is convenient for local tools, but it requires AWS CLI v2 and an interactive session. Workload roles are non-interactive and better for deployment, while OIDC is better for external automation.

Account guard for mutating tools

For a deployment or cleanup utility, make the expected account an explicit input and stop before the first mutation when it differs. This protects against a valid session for the wrong account—a failure that credential refresh cannot detect.

1
2
3
4
5
6


const expectedAccount = process.env.EXPECTED_AWS_ACCOUNT_ID;
if (!expectedAccount || identity.Account !== expectedAccount) {
 throw new Error(
 `Refusing to continue: expected ${expectedAccount}, resolved ${identity.Account}`
 );
}

Also test three negative paths: no cached session, a profile that is configured but not authorized for the account, and a permission set that can authenticate but cannot perform the service action. Authentication success and authorization success are separate facts. When reporting failure, include the non-sensitive profile, account, role ARN, Region, AWS request ID, and error name; redact tokens and signed headers.

For long-running local processes, keep the provider function attached to each SDK client so it can refresh. Resolving it once at startup and converting it into a plain credential object discards that advantage. If the process must run unattended for days, a human SSO session is the wrong operational identity; move it to a managed workload or an external workload federation flow.

Verified on 2026-08-01.

Official sources

AWS Access in 2026: Federation and Temporary Credentials First

Yoonsoo Park — Mon, 22 May 2023 01:25:00 -0400

The useful question is no longer “IAM user or IAM role?” It is “who needs access, where does the code run, and which temporary credential mechanism fits that boundary?”

AWS currently recommends temporary credentials for both people and workloads. IAM users still exist, but they are an exception for cases that cannot use federation or roles—not the normal starting point.

The current mental model

An IAM user is a long-lived identity inside one AWS account. Its password and access keys remain usable until they are rotated or revoked. That persistence increases the cost of accidental disclosure.

An IAM role has permissions and a trust policy but no long-lived credentials. When a person, workload, or AWS service assumes it, AWS Security Token Service issues an access key, secret key, and session token that expire. The trust policy answers who may assume the role; its permissions answer what an assumed session may do.

Use these defaults:

Workforce access: federate through AWS IAM Identity Center or another identity provider. Assign permission sets to groups, not one-off user policies.
AWS workloads: attach a service role to Lambda, ECS tasks, EC2 instances, or other compute. Let the AWS SDK default credential provider discover it.
External CI/CD: use workload identity federation such as GitHub Actions OIDC to assume a narrowly scoped role.
Cross-account access: assume a role in the target account, with explicit trust and conditions.
Unsupported legacy workload: use an IAM user only after ruling out roles and federation. Scope and rotate its keys, monitor their use, and plan its removal.

A safe local workflow

Configure IAM Identity Center with AWS CLI v2:

1
2
3


aws configure sso --profile engineering-dev
aws sso login --profile engineering-dev
aws sts get-caller-identity --profile engineering-dev

The last command is an important verification step: confirm the account and ARN before making changes. Applications should select the profile and let the SDK resolve temporary credentials. Do not copy the generated access key into source code or .env files.

1

AWS_PROFILE=engineering-dev aws s3api list-buckets

For an AWS-hosted workload, do not run aws configure in the container. Attach an execution or task role and construct SDK clients without explicit keys.

Permission design

Temporary credentials reduce credential lifetime; they do not make broad permissions safe. Start with the access needed to get a workload running, then use IAM Access Analyzer and observed activity to tighten it. Add conditions where they meaningfully constrain the request: organization ID, source account, resource tags, or a specific OIDC subject.

Require phishing-resistant MFA where available for human access. Protect the root user separately and do not create root access keys. Review unused roles, permission sets, policies, and credentials on a schedule.

Tradeoffs

Identity Center adds central configuration and depends on a working identity source, but it gives one place for account assignments and short-lived sessions. Service roles are easy on AWS compute but do not directly solve access from arbitrary external hosts. OIDC removes stored CI secrets but requires careful audience and subject conditions. IAM users can support a small set of legacy integrations, at the cost of rotation, storage, monitoring, and incident-response work.

Migration checklist

Inventory IAM users, access keys, last-used data, and their real owners.
Classify each identity as human, AWS workload, external workload, or break-glass use.
Create permission sets or roles with equivalent, preferably narrower, permissions.
Test with sts get-caller-identity and representative read/write operations.
Update applications to use the default provider chain rather than explicit keys.
Monitor CloudTrail during a defined overlap period.
Deactivate an old key before deleting it; roll back only if a verified dependency still uses it.
Remove unused IAM users and document any justified exception.

Verified against official documentation on 2026-08-01.

Official sources

The Observer Pattern

Yoonsoo Park — Sun, 21 May 2023 01:25:00 -0400

Understanding the Observer Pattern in TypeScript: A Comprehensive Guide

The Observer pattern is a design pattern in which an object, known as the subject, maintains a list of its dependents, called observers, and notifies them automatically of any state changes, typically by calling one of their methods.

This pattern is particularly useful when you want to ensure multiple parts of your application are notified when another part changes. It fosters a degree of loose coupling between different parts of an application.

How does the Observer Pattern Work?

Let’s break down the main components of the Observer pattern:

Subject: The subject holds the state and oversees the observers. It provides the methods to register and unregister observers. Moreover, it has a method to notify all observers of a state change.
Observer: Observers are objects that follow the state of the subject. They expose a method that gets called when the subject’s state changes.
Concrete Subject: It’s the object having the state that other objects are interested in. It extends the Subject class.
Concrete Observer: These are the real objects that are observing the state. They extend the Observer class.

Example with TypeScript

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53


interface Subject {
 registerObserver(o: Observer): void;
 removeObserver(o: Observer): void;
 notifyObservers(): void;
}

interface Observer {
 update(temperature: number): void;
}

class WeatherStation implements Subject {
 private temperature: number;
 private observers: Observer[] = [];

 setTemperature(temp: number) {
 console.log('WeatherStation: new temperature measurement: ' + temp);
 this.temperature = temp;
 this.notifyObservers();
 }

 registerObserver(o: Observer) {
 this.observers.push(o);
 }

 removeObserver(o: Observer) {
 let index = this.observers.indexOf(o);
 this.observers.splice(index, 1);
 }

 notifyObservers() {
 for (let observer of this.observers) {
 observer.update(this.temperature);
 }
 }
}

class TemperatureDisplay implements Observer {
 private subject: Subject;

 constructor(weatherStation: Subject) {
 this.subject = weatherStation;
 weatherStation.registerObserver(this);
 }

 public update(temperature: number) {
 console.log('TemperatureDisplay: I need to update my display');
 // Logic would go here
 }
}

let weatherStation = new WeatherStation();
let tempDisplay = new TemperatureDisplay(weatherStation);
weatherStation.setTemperature(20);

In the example above, the WeatherStation is the subject that maintains the list of observers and notifies them of any changes. TemperatureDisplay is the observer that gets notified of the changes.

The observer pattern is useful when several consumers need notification of state changes. Define unsubscribe and error behavior explicitly so observers do not leak resources or silently stop receiving events.

The Decorator Pattern

Yoonsoo Park — Sat, 20 May 2023 01:25:00 -0400

The Decorator Pattern with TypeScript

The Decorator Pattern is one of the most powerful structural design patterns in the software development arsenal, granting flexibility and dynamism in extending object behavior.

What is the Decorator Pattern?

The Decorator Pattern is a design pattern that allows behavior to be added to individual objects, either statically or dynamically, without affecting the behavior of other objects from the same class. Decorators provide a flexible alternative to subclassing for extending functionality.

When Should You Use the Decorator Pattern?

The Decorator Pattern provides an alternative to subclassing, which involves creating a new class for every new behavior.

Use the Decorator Pattern when:

You want to add responsibilities to individual objects dynamically and transparently, that is, without affecting other objects.
You want to add responsibilities to an object that you may want to change in the future.
Extending functionality by subclassing is impractical because it leads to a large number of subclasses and complicates code maintenance and error tracking.

Example with TypeScript

Let’s assume we are developing a text editor, and we want to have the ability to add various types of formatting to the text, such as bold, italic, or underline. Here is how we can implement this using the Decorator Pattern:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39


// Base Component
interface Text {
 displayText(): string;
}

// Concrete Component
class PlainText implements Text {
 displayText(): string {
 return "Plain Text";
 }
}

// Base Decorator
class TextDecorator implements Text {
 constructor(protected text: Text) {}
 displayText(): string {
 return this.text.displayText();
 }
}

// Concrete Decorators
class BoldText extends TextDecorator {
 displayText(): string {
 return `Bold(${super.displayText()})`;
 }
}

class ItalicText extends TextDecorator {
 displayText(): string {
 return `Italic(${super.displayText()})`;
 }
}

// Usage
let text: Text = new PlainText();
text = new BoldText(text);
text = new ItalicText(text);

console.log(text.displayText()); // Outputs: Italic(Bold(Plain Text))

In this example, we’re able to apply multiple formatting options (bold, italic) to our text dynamically, and we can easily introduce more (like underline, strikethrough, etc.) without affecting existing classes.

Wrapping up

The Decorator Pattern is a highly effective tool in a developer’s toolbox, offering dynamic and flexible object behavior. It aligns well with the open-closed principle, one of the five principles of SOLID, leading to more maintainable and less error-prone code. Used appropriately and sparingly, the Decorator Pattern can greatly improve your code design and structure.

Strategy Pattern in Dependency Injection

Yoonsoo Park — Fri, 19 May 2023 01:25:00 -0400

Understanding the Concepts

Strategy Pattern

The Strategy Pattern is a behavioral design pattern that encapsulates algorithms into separate classes with a common interface, enabling interchangeability within the original context object. This approach enhances flexibility by allowing the switching of algorithms or logic at runtime.

Dependency Injection

Dependency Injection is a technique that promotes Inversion of Control (IoC) - an object obtains its dependencies from an external source rather than creating them itself. DI is instrumental in developing code that is more manageable, modular, and testable.

Bridging Strategy Pattern with Dependency Injection

When combined, these two concepts can provide exceptional benefits. Dependency Injection can be used to inject different Strategy objects into a class, thus promoting flexible behavior that varies with the injected strategy.

A Practical Example

Let’s consider a simple example: a TextFormatter class that formats a given text in different ways, such as lower case, upper case, or capitalized. We’ll use a Python-esque pseudo-code for our demonstration.

Firstly, we define the strategy interface and the concrete strategies.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15


class TextFormatStrategy:
 def format_text(self, text):
 pass

class LowerCaseStrategy(TextFormatStrategy):
 def format_text(self, text):
 return text.lower()

class UpperCaseStrategy(TextFormatStrategy):
 def format_text(self, text):
 return text.upper()

class CapitalizeStrategy(TextFormatStrategy):
 def format_text(self, text):
 return text.capitalize()

Next, we define the TextFormatter class which will use Dependency Injection to accept a TextFormatStrategy object.

1
2
3
4
5
6


class TextFormatter:
 def __init__(self, strategy: TextFormatStrategy):
 self._strategy = strategy

 def format(self, text):
 return self._strategy.format_text(text)

Now we can change the behavior of the TextFormatter class at runtime by injecting different strategies.

1
2
3
4
5
6
7
8


formatter = TextFormatter(LowerCaseStrategy())
print(formatter.format("Hello World")) # Output: "hello world"

formatter = TextFormatter(UpperCaseStrategy())
print(formatter.format("Hello World")) # Output: "HELLO WORLD"

formatter = TextFormatter(CapitalizeStrategy())
print(formatter.format("hello world")) # Output: "Hello world"

This example demonstrates how Dependency Injection can inject different strategies into a class, resulting in dynamic behavior changes based on the provided strategy.

--save-dev in npm

Yoonsoo Park — Thu, 18 May 2023 01:25:00 -0400

When working with npm (Node Package Manager) to manage dependencies in a Node.js project, the --save-dev flag is often used to save packages as development dependencies. It is an essential feature that helps distinguish between packages required for development purposes and those needed for the production environment.

What does `--save-dev` do?

By appending --save-dev to an npm install command, you specify that the package being installed is only required during development and should not be included when deploying your application to a production environment. The package will be added to the devDependencies section in your package.json file.

1

npm install <package-name> --save-dev

The devDependencies section typically includes packages related to testing, building, and development tooling, such as test frameworks (e.g., Mocha or Jest), build tools (e.g., Gulp or Webpack), linters (e.g., ESLint or Prettier), and other utilities.

Example use cases for `--save-dev`

Testing frameworks: When writing tests for your application, you often rely on specific testing frameworks like Mocha or Jest. These frameworks are not needed in production but are crucial during development and continuous integration processes. By installing them with --save-dev, you ensure they are available when running tests but won’t unnecessarily bloat your production build.
Build tools: Build tools such as Gulp, Grunt, or Webpack are commonly employed during development to compile and bundle assets, optimize code, or perform other build-related tasks. These tools are not required in a production environment, as the bundled code can be executed without them. Therefore, it’s advisable to save them as development dependencies using --save-dev.
Linters and code formatters: Linters, such as ESLint, and code formatters, like Prettier, assist in maintaining consistent code quality and style. They provide valuable feedback during development but are not necessary for the deployed application. Including them as devDependencies allows developers to use them while working on the codebase, without affecting the production build.

When not to use `--save-dev`

Although --save-dev is useful in many scenarios, there are situations where it should not be employed. One example is when installing packages that are explicitly required at runtime by your application. These packages provide functionality that is essential for the application to run correctly, regardless of the development or production context.

For instance, consider a web server framework like Express. Express is a core dependency for a Node.js web application and is necessary for the application to function correctly. In this case, you should install Express without using --save-dev, as it belongs to the regular dependencies section of your package.json file:

1

npm install express

By installing Express as a regular dependency, it will be bundled and deployed along with your application to ensure proper execution in both development and production environment.

The Strategy Pattern

Yoonsoo Park — Wed, 17 May 2023 01:25:00 -0400

The ability to modify or extend functionality without impacting the existing codebase is crucial in a rapidly evolving technological landscape. One design pattern that helps achieve this goal is the Strategy Pattern.

Understanding the Strategy Pattern

The Strategy Pattern is a behavioral design pattern that enables the definition of a family of algorithms, encapsulates each one as a separate class, and makes them interchangeable at runtime. It allows the algorithm to vary independently from the clients that use it, promoting loose coupling between objects and providing a way to select algorithms dynamically.

At the heart of the Strategy Pattern are three main components:

Context: This is the class that contains the main business logic and maintains a reference to the chosen strategy object. It provides a method for clients to set the strategy or change it dynamically during runtime.
Strategy: The strategy interface defines a common set of methods that encapsulate different algorithms or behaviors. Each strategy represents a concrete implementation of a particular algorithm.
Concrete Strategies: These are the classes that implement the strategy interface and provide specific implementations of the algorithms or behaviors.

Advantages of the Strategy Pattern

The Strategy Pattern offers several benefits in software design:

Improved Code Reusability By encapsulating algorithms within separate strategy classes, the Strategy Pattern promotes code reuse. Different parts of the system can utilize the same set of strategies, enhancing maintainability and reducing code duplication. This reusability simplifies future modifications or additions to the system.
Enhanced Flexibility and Extensibility The Strategy Pattern allows for easy extension and modification of behaviors. Adding a new strategy involves creating a new class that implements the strategy interface, without needing to modify existing code. This flexibility enables dynamic selection of strategies at runtime, enabling the system to adapt to changing requirements.
Separation of Concerns The Strategy Pattern separates the logic of an algorithm from the context that uses it. This separation promotes cleaner code architecture by assigning responsibilities to appropriate classes. The context class focuses on the main business logic, while the strategies encapsulate specific algorithms. It enhances the overall maintainability and readability of the codebase.
Improved Testability Because the Strategy Pattern encapsulates algorithms within separate classes, it becomes easier to test each strategy independently. By isolating the behavior in smaller, self-contained units, unit testing and mocking become more straightforward, resulting in better test coverage and more robust software.
Runtime Selection of Algorithms One of the key advantages of the Strategy Pattern is the ability to select algorithms dynamically during runtime. The context can change the strategy it uses without affecting the clients or requiring complex conditional logic. This dynamic behavior selection provides a powerful mechanism for adapting the system’s behavior to different scenarios or user preferences.

Example

Let’s consider an example where we want to implement different sorting algorithms for a list of integers using the Strategy Pattern. We’ll have a Sorter class as the context, a SortStrategy interface as the strategy, and multiple concrete strategy classes for different sorting algorithms.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46


# Step 1: Define the strategy interface
class SortStrategy:
 def sort(self, data):
 pass

# Step 2: Implement concrete strategy classes
class BubbleSortStrategy(SortStrategy):
 def sort(self, data):
 # Implementation of bubble sort algorithm
 print("Sorting using Bubble Sort")
 # ...

class QuickSortStrategy(SortStrategy):
 def sort(self, data):
 # Implementation of quicksort algorithm
 print("Sorting using Quick Sort")
 # ...

class MergeSortStrategy(SortStrategy):
 def sort(self, data):
 # Implementation of merge sort algorithm
 print("Sorting using Merge Sort")
 # ...

# Step 3: Create the context class
class Sorter:
 def __init__(self, strategy):
 self.strategy = strategy

 def set_strategy(self, strategy):
 self.strategy = strategy

 def sort(self, data):
 self.strategy.sort(data)

# Step 4: Client code
data = [5, 2, 7, 1, 9]

sorter = Sorter(BubbleSortStrategy())
sorter.sort(data) # Sorting using Bubble Sort

sorter.set_strategy(QuickSortStrategy())
sorter.sort(data) # Sorting using Quick Sort

sorter.set_strategy(MergeSortStrategy())
sorter.sort(data) # Sorting using Merge Sort

In the above example, we define the SortStrategy interface that declares the sort() method. We then implement concrete strategy classes such as BubbleSortStrategy, QuickSortStrategy, and MergeSortStrategy, each providing their own implementation of the sort() method.

Next, we create the Sorter class as the context. It has a reference to the SortStrategy interface and provides methods to set the strategy dynamically (set_strategy()) and invoke the sorting operation (sort()).

In the client code, we instantiate a Sorter object and initially set it to use the BubbleSortStrategy. We call the sort() method on the Sorter object, and it delegates the sorting operation to the currently set strategy (BubbleSortStrategy).

We can dynamically change the sorting strategy by calling set_strategy() with a different strategy object (QuickSortStrategy, MergeSortStrategy, etc.). The Sorter object will then use the new strategy for subsequent sorting operations.

Upsert Salesforce Data from CSV with sf CLI

Yoonsoo Park — Tue, 16 May 2023 01:25:00 -0400

Verified on 2026-08-01. Records are loaded, not deployed, and the retired command’s mapping-file flag is not part of the current bulk upsert workflow.

Prepare UTF-8 CSV with a stable external ID, then use the current command and inspect the job result:

1
2


sf data upsert bulk --sobject Widget__c --file widgets.csv \
 --external-id External_Id__c --target-org staging --wait 10

Test a small file first. Keep failed and unprocessed result files, avoid logging sensitive rows, and respect field-level access and validation rules. Bulk is efficient for large asynchronous loads; sf data upsert record or an API client is simpler for a handful of records and easier to handle transaction by transaction.

Migration: remove mapping.json, make CSV headers match API field names, confirm the external-ID field, run in a sandbox, reconcile counts, then promote the same reviewed file and command to the intended org.

References: Salesforce CLI data commands, Bulk API 2.0.

Current mental model

Metadata deployment changes schema and configuration. Data loading creates or changes records and triggers validation rules, Flows, Apex, duplicate rules, sharing, and downstream integrations. An upsert chooses insert or update by an external ID, so the stability and uniqueness of that key determine whether reruns are safe.

Prepare and execute safely

Start with a representative sample that contains no unnecessary sensitive columns. Confirm field API names, data types, picklist values, locale-sensitive dates, UTF-8 encoding, and the external-ID field. Query a few keys first to understand collision behavior.

1
2
3
4


sf data query --target-org staging \
 --query "SELECT Id, External_Id__c FROM Widget__c LIMIT 5" --json
sf data upsert bulk --sobject Widget__c --file widgets-sample.csv \
 --external-id External_Id__c --target-org staging --wait 10

Reconcile successful, failed, and unprocessed counts with the input. Read failure files instead of blindly rerunning the whole batch. When lookup relationships are involved, load parents first or resolve stable external IDs; do not copy Salesforce record IDs between environments.

Alternatives and tradeoffs

Bulk API 2.0 minimizes client orchestration for large files but is asynchronous and can produce partial success. Record commands are clearer for small operational changes. A purpose-built integration can provide transformations, retries, and observability but requires ownership and testing. Data Loader remains useful for supervised admin work, though its configuration must be reviewed like code.

Migration and verification checklist

Remove the obsolete mapping flag, rename “deploy” jobs to “load” or “upsert,” and version-control a schema-only sample rather than customer data. Test automation and validation side effects in a sandbox, define retry rules for failed rows, take an appropriate backup, and document rollback. After loading, compare counts, sample fields by external ID, inspect automation failures, and rerun the sample to prove idempotency.

git diff with Two Tags using simple-git TypeScript

Yoonsoo Park — Mon, 15 May 2023 01:25:00 -0400

Repository and reference safety

Treat repository URLs, refs, and output paths as untrusted input. Use a unique temporary directory, pass refs as separate arguments, validate that they resolve to commits, and remove the directory in finally. Confirm the installed simple-git version because its TypeScript return types have changed across releases.

Performing Git Diff with simple-git

First, make sure you have the simple-git library imported in your TypeScript file:

1

import simpleGit, { SimpleGit } from "simple-git";

Create a function that will perform the Git diff operation between two tags. The function should accept the tag names as parameters and return a promise that resolves to the diff output string.

1
2
3
4
5
6
7


async function getGitDiff(tag1: string, tag2: string): Promise<string> {
 const git: SimpleGit = simpleGit();

 await git.revparse(["--verify", `${tag1}^{commit}`]);
 await git.revparse(["--verify", `${tag2}^{commit}`]);
 return git.diff([tag1, tag2]);
}

The refs are verified as commits before they are passed as separate git diff arguments. Current simple-git releases return the textual diff from this overload. Pin the package version and compile the example because older releases exposed different typings.

Now you can call the getGitDiff function and retrieve the diff output between two tags:

1
2
3
4
5


const tag1: string = "v1.0.0";
const tag2: string = "v1.1.0";

const diff: string = await getGitDiff(tag1, tag2);
console.log(diff);

Use case: clone the repo to local drive then perform git diff

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21


import simpleGit from "simple-git";
import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";

async function gitDiff(
 repositoryUrl: string,
 tag1: string,
 tag2: string
): Promise<string> {
 const tempDir = await mkdtemp(join(tmpdir(), "tag-diff-"));
 try {
 await simpleGit().clone(repositoryUrl, tempDir, ["--no-checkout"]);
 const git = simpleGit(tempDir);
 await git.revparse(["--verify", `${tag1}^{commit}`]);
 await git.revparse(["--verify", `${tag2}^{commit}`]);
 return await git.diff([tag1, tag2]);
 } finally {
 await rm(tempDir, { recursive: true, force: true });
 }
}

This function is appropriate only when the caller is allowed to clone the supplied repository. Production services should also restrict protocols and hosts, set time and size limits, and avoid logging credentials embedded in a URL.

DTO vs Schema

Yoonsoo Park — Sun, 14 May 2023 01:25:00 -0400

Data Transfer Object (DTO)

A DTO is a plain TypeScript/JavaScript object used for transferring data between different layers or components of an application. Its primary purpose is to encapsulate data and provide a clear structure for communication across system boundaries, such as API calls or database interactions.

Let’s consider an example of a UserDTO in TypeScript:

1
2
3
4
5


interface UserDTO {
id: number;
name: string;
email: string;
}

In this case, the UserDTO interface defines the structure of user data that can be transferred between components or sent over the network. It includes properties like id, name, and email, allowing a consistent and well-defined data representation during communication.

DTOs help decouple different parts of an application by providing a contract for data exchange. They enable type checking and validation when passing data between components, enhancing code reliability and reducing the chances of data-related bugs.

Schema

A schema, on the other hand, describes the structure, constraints, and relationships of data within an application. It serves as a formal definition for expected data shapes and validation rules. Schemas are commonly employed in libraries or frameworks that handle data validation, serialization, or storage.

To illustrate the concept of a schema in TypeScript, we can use a popular library called Yup:

1
2
3
4
5
6
7


import * as yup from 'yup';

const userSchema = yup.object().shape({
 id: yup.number().required(),
 name: yup.string().required(),
 email: yup.string().email().required(),
});

In this example, we create a userSchema using the Yup library. It defines the expected structure and validation rules for user data. The schema specifies that the id, name, and email fields are required, and the email field should be a valid email address.

Schemas provide a powerful mechanism for validating data integrity and enforcing consistency within an application. They allow you to define complex validation rules, perform data transformations, and handle error conditions effectively.

DTO vs Schema

While DTOs and schemas share some similarities, they have distinct purposes within an application.

DTOs focus on transferring data between components or across system boundaries.
- DTOs excel at enabling clear communication and decoupling between different parts of an application. They ensure consistency and type safety when passing data, reducing potential errors and making code more maintainable.
Schemas concentrate on defining and validating the structure of data within an application.
- schemas provide a mechanism for formally defining data structures and applying validation rules. They enhance data integrity, enforce constraints, and facilitate robust data handling throughout an application.

Tomorrow is Monday guys. yike.. Good luck!

thats.nono

Give Every Agent Its Own Worktree

The failure mode isolation prevents

What I already do by hand

The same pattern one level up

The tradeoff, honestly

What to actually do

Irreversible Actions Cannot Be Gated by a Prompt

Why the prompt is the wrong layer

The time I was the rogue agent

What the code layer actually looks like

The general principle

What to actually do

I Rebuilt the AWS Restaurant Pricing Swarm as a Surf School, Then Ran It 33 Times

The pattern, retargeted to a surf school

What the diagram shows vs. what 33 runs showed

1. The last agent is the most expensive and the most fragile

2. Temperature zero did not make it deterministic

3. The arrows hide malformed tool calls and SDK edges

4. Compact handoffs cut cost almost in half, and it still wasn’t cheap

About that safety veto

So should you build the restaurant swarm?

How to Use Cross-Session Messaging in Claude Code

Check the version first

Give sessions stable names

Write a message as a work contract

Patterns that work well

Propagate a contract across repositories

Connect implementation and review sessions

Unblock work with one precise question

Collect status from independent sessions

This is not Agent Teams

Treat permissions and delivery failures as normal states

Keep durable state outside messages

A practical checklist

MCP Goes Stateless (2026-07-28): Host, Client, Server, and What Changes on AWS

Host, client, server in three minutes

What changed: the session left the protocol

What you have to change in an existing server

What changes when you deploy on AWS

How this relates to AgentCore

Pitfalls I expect people to hit

What to actually do

How Much Does It Cost to Run Hermes Agent on AWS?

The measured architecture

The measured usage cost: about $108.9

Why the cash bill was close to $0

The EFS throughput surprise

NAT Gateway charges even with low traffic

What I would estimate first next time

Migrating Hermes from AWS ECS to Synology Without Losing Its Memory

The target architecture

Pin the runtime before moving data

Stop AWS before taking the final backup

A SQLite database is more than state.db

Build a new NAS generation

Two Dockge failures worth remembering

The security boundary changed

Rollback does not always mean “start AWS”

Closing thoughts

References

AgentCore Runtime Instances: When Your Agent Outgrows the MicroVM

One running example

Where it fits

Before: bending the microVM to fit

After: pick the compute, attach, done

Which one

Pitfalls

What to do

DynamoDB Now Does Vector Search: When It Replaces Your Vector DB (and When It Doesn't)

The running example

Before: a second database and a pipeline to keep it honest

After: the vector is just an attribute

Multi-tenant isolation: the partition key does real work here

So when does this actually replace your vector DB?

Pitfalls

What to actually do

Using AgentCore Identity Without a Shared Client Secret

Where Identity fits in AgentCore

Before: the shared client secret

A SQLite database is more than `state.db`